Create a broken-link checker

This document describes how to configure a periodic test of thethe links contained in a URI by creating a synthetic monitor. You specify theoptions for the test, such as the origin URI, the number of links tested,and the number of retries,and then deploy a preconfigured Cloud Run function.To support your troubleshoot and debug efforts, synthetic monitors save detailedinformation about each test, including screenshots. Screenshots let you viewthe exact response seen by the customers of your application.

To learn more about synthetic monitors, seeAbout synthetic monitors.

This feature is supported only for Google Cloud projects.ForApp Hubconfigurations, select the App Hub host project or management project.

About broken-link checkers

Each broken-link checker tests the links serially, and there is an overallsynthetic timeout, which is configurable.

By default, a broken-link checker does the following:

  • Searches the origin URI for HTML anchor elements withhref attributes.
  • Tests the first 10 links found on the origin URI.
  • For each link, the checker issues a request and then waits at most30 seconds for a response. When a response is received, the checkerverifies that theHTTP response status is200, which indicates a successful response.The checker doesn't perform retries.

You specify the origin URI. You can configure which HTML elements that thebroken-link checker searches for, the maximum number of elements tested,the per-test timeout, and whether retries are performed. You can also configurebroken-link checkers to wait for a selector to appear.

Broken-link checkers use thebroken-links-oktemplate. The configuration for a broken-link checker is specified by theoptions object of theindex.js file. If you create your checker by using theGoogle Cloud console, you're prompted for each configuration option andthe Cloud Run function is updated for you. However, if you use theCloud Monitoring API or Terraform, then you must populate this object.

After you create a broken-link checker, to modify the configuration, updatetheoptions object and redeploy the Cloud Run function.

Before you begin

Complete the following steps in the Google Cloud project that will store thelink checker:

  1. To get the permissions that you need to view and modify synthetic monitors by using the Google Cloud console, ask your administrator to grant you the following IAM roles on your project:

    For more information about granting roles, seeManage access to projects, folders, and organizations.

    You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

  2. Enable the Cloud Monitoring API, Artifact Registry API, Cloud Build API,Cloud Functions API, Cloud Logging API, Pub/Sub API, and Cloud Run Admin API APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the APIs

  3. Verify that your Google Cloud project contains the default Compute Engine service account. This service account is created when you enable the Compute Engine API and has a name similar to12345-compute@developer.gserviceaccount.com.

    In the Google Cloud console, go to theService Accounts page:

    Go toService Accounts

    If you use the search bar to find this page, then select the result whose subheading isIAM & Admin.

    If the default Compute Engine service account doesn't exist, then clickCreate service account and complete the dialog.

  4. Ensure that the default Compute Engine service account, or the service account that you created, has been granted the role of Editor (roles/editor).

    To view the roles granted to your service account, do the following:

    1. In the Google Cloud console, go to theIAM page:

      Go toIAM

      If you use the search bar to find this page, then select the result whose subheading isIAM & Admin.

    2. SelectInclude Google-provided role grants.
    3. If the service account used by your synthetic monitor isn't listed, or if it hasn't been granted a role that includes the permissions in the role of Cloud Trace Agent (roles/cloudtrace.agent), then grant this role to your service account.
  5. Configure the notification channels that you want to use to receive notifications. We recommend that you create multiple types of notification channels. For more information, seeCreate and manage notification channels andCreate and manage notification channels by API.

  6. Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    Terraform

    To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

      Install the Google Cloud CLI.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account:

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

Create a broken-link checker

Console

When you create a synthetic monitor by using the Google Cloud console, a newCloud Run function (2nd gen)is deployed and the monitor for that Cloud Run function is created.You can't create a synthetic monitor that monitors anexisting Cloud Run function.

  1. Ensure that you've enabled therequired APIs, that your project containsa default Compute Engine service account, and that this account hasbeen granted the role of Editor (roles/editor). For more information,seeBefore you begin.

  2. In the Google Cloud console, go to the Synthetic monitoring page:

    Go toSynthetic monitoring

    If you use the search bar to find this page, then select the result whose subheading isMonitoring.

  3. In the toolbar of the Google Cloud console,select your Google Cloud project. ForApp Hubconfigurations, select the App Hub host project or management project.
  4. SelectCreate Synthetic Monitor.
  5. For the template, selectBroken link checker.
  6. Enter a name for the synthetic monitor.

  7. Optional: Update theResponse Timeout, theCheck Frequency, andadd user-defined labels.

  8. Configure the URI and the elements to test:

    Note: The values in theURI configuration fieldsare copied to theOptions object in theindex.js file when you clickCreate Function. After you clickCreate Function, to change theconfiguration, edit theOptions object. For details, seeEdit a synthetic monitor or Cloud Run function.

    1. ClickOrigin URI, and enter a URI that you want tested. The valuethat you enter must be an HTTP or HTTPS endpoint. For example,you might enterhttps://mywebsite.example.com.

    2. Optional: In theNumber of links to follow, update the maximumnumber of links that are tested. The default value of this field is10.

    3. Optional: In theHTML element selector field, enter the HTMLelement that you want matched, as a comma separated list.The value that you enter is converted to a string and then passed totheDocument: querySelectorAll() method.

      By default, this field is set toa, which matches anchors. Youcan enter values such asa, img, when you want to match both anchorsand images.

    4. Optional: In theHTML attributes to follow field, enter theHTML attributes that you want matched. The comma separated values thatyou enter are individuallypassed to thegetAttribute() method.

      By default, this field is set tohref, which specifies the URI forthe link. You can enter multiple attributes, for example, you canenterhref, src. In this example, the code searches for theattributehref and then searches for the attributesrc.

    5. Optional: Configure wait for selector, per-URI timeout, retries, andexpected status codes:

      1. ClickShow more options.

      2. To configure the broken-link checker to wait for a specificselector to appear in the URI before any links are scraped, enter theCSS selectors in theWait for element selector field.The value that you enter is converted to a string and then passed to thepage.waitForSelector() method.

        If the selector doesn't appear before the timeout expires, then thefailure is recorded in the logs.

      3. Update the order in which links are selected for testing.

      4. Configure retries.

        By default, one request is sent to each link and if the initialrequest fails for any reason, for example, the command times out orthe HTTP status code isn't200, then the link is marked as failed.

        This field specifies the number of times the broken-link checkercan issue an HTTP request to a link before marking the link as failed.

      5. Configure a timeout that applies to each URI. By default, this valueis set to 30 seconds.

      6. To specify the expected status code and time out for a specific URI,clickAdd per-link option and complete the dialog.

  9. Optional: Configure whether screenshots of responses are collected andsaved. If you use the default settings, then screenshots aren't saved.If you enable screenshot collection, then you can collect screenshots forall tests or only for failing tests. Cloud Monitoring usesthe following convention to name the Cloud Storage bucket:

    gcm-PROJECT_ID-synthetics-LOCATION

    In the previous expression:

    • PROJECT_ID: The ID of your Google Cloud project.
    • LOCATION: The location of your Cloud Storage bucket.

    You have the option to use an existing Cloud Storage bucket.

  10. Review your configuration and ensure that it is correct and complete,and then create your Cloud Run function:

    1. ClickCreate Function.

      The values in theURI configuration fieldsare copied to theOptions object in theindex.js file when you clickCreate Function. After you clickCreate Function, to change theconfiguration, edit theOptions object.

    2. Enter a display name and select a region. Names must be unique within aregion.

      Note: Don'tinclude an underscore in the nameof your Cloud Run function.

    3. In theRuntime, build, connections and security settings section,do the following:

    4. ClickApply function.

  11. Configure thealerting policy:

    1. Optional: Update the alerting policy name and the duration of failurebefore notifications are sent.

    2. Add the notification channels.

  12. ClickCreate.

    The Cloud Run function that you defined is built and deployed as2nd gen, and the synthetic monitor is created.

Terraform

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands. For more information, see theTerraform provider reference documentation.

The process of creating a broken-link checker checker by usingTerraform is identical to the process of creating any othersynthetic monitor.For information about using the Terraform to create a synthetic monitor,seeCreate a synthetic monitor, and select theTerraform tab.

Note: Don'tinclude an underscore in the nameof your Cloud Run function.

Broken-link checkers use thebroken-links-oktemplate. The configuration for a broken-link checker is specified by theoptions object of theindex.js file.

When theoptions.screenshot_options structure is defined, thebroken-link checker collects screenshots and saves them to aCloud Storage bucket.If thescreenshot_options.storage_location field isn't defined or if thevalue is an empty string, then Monitoring creates aCloud Storage bucket and screenshots are saved to that bucket.Monitoring uses the following convention to name theCloud Storage bucket:

gcm-PROJECT_ID-synthetics-LOCATION

In the previous expression:

  • PROJECT_ID: The ID of your Google Cloud project.
  • LOCATION: The location of your Cloud Storage bucket.

REST

The process of creating a broken-link checker checker by using theCloud Monitoring API is identical to the process of creating any othersynthetic monitor.For information about using the Cloud Monitoring API to create a synthetic monitor,seeCreate a synthetic monitor, and select theCloud Monitoring tab.

Note: Don'tinclude an underscore in the nameof your Cloud Run function.

Broken-link checkers use thebroken-links-oktemplate. The configuration for a broken-link checker is specified by theoptions object of theindex.js file.

When theoptions.screenshot_options structure is defined, thebroken-link checker collects screenshots and saves them to aCloud Storage bucket.If thescreenshot_options.storage_location field isn't defined or if thevalue is an empty string, then Monitoring creates aCloud Storage bucket and screenshots are saved to that bucket.Monitoring uses the following convention to name theCloud Storage bucket:

gcm-PROJECT_ID-synthetics-LOCATION

In the previous expression:

  • PROJECT_ID: The ID of your Google Cloud project.
  • LOCATION: The location of your Cloud Storage bucket.

Explore results

For each execution, a broken-link checker does the following:

  • Generates a table, where each row provides information about the testing ofa specific URI. The summary information includes the target URI, latency,status, and the HTML element identifier. For example, this column listsa when an HTML anchor element is tested. When the row corresponds tothe origin URI, the value of HTML element identifier is-.

  • Collects metrics, trace data, and log data.

  • Collects screenshots, when configured.

For more information about how to explore the collected data, seeExplore synthetic monitor results.

Troubleshoot

This section provides information that you can use to help you troubleshootyour broken-link checkers.

Unable to edit the configuration of a broken-link checker

You created a broken-link checker by using the Google Cloud console, and you wantto change the HTML elements that are tested, or you want to modifythe URI timeout, retries, wait for selector, and per-link options.However, when you edit the broken-link checker, the Google Cloud console doesn'tdisplay the configuration fields.

To resolve this failure, do the following:

  1. In the Google Cloud console, go to the Synthetic monitoring page:

    Go toSynthetic monitoring

    If you use the search bar to find this page, then select the result whose subheading isMonitoring.

  2. In the toolbar of the Google Cloud console,select your Google Cloud project. ForApp Hubconfigurations, select the App Hub host project or management project.
  3. Locate the synthetic monitor that you want to edit,clickMore options, and then selectEdit.
  4. ClickEdit function.

  5. Edit theoptions object in theindex.js file, and thenclickApply function.

    For information about the fields and syntax for this object, seebroken-links-ok/index.js.

  6. ClickSave.

Google Cloud console displays that saves of screenshots fail

Note: A synthetic monitor that can't save screenshots continues totest the links contained in a URI.

You created a broken-link checker and configured it to save screenshots.However, the Google Cloud console is displaying one of the following warningmessages along with more detailed information:

  • InvalidStorageLocation
  • StorageValidationError
  • BucketCreationError
  • ScreenshotFileUploadError

To resolve these failures, try the following:

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.