Manage synthetic monitors

This document describes how to manage your synthetic monitors. You can view a list of your synthetic monitors, and for each synthetic monitor, you can view and modify the configuration, view the execution history, and view details about each execution. You can manage your synthetic monitors by using the Google Cloud console or by using the Cloud Monitoring API.

For information about how to explore the execution results and the metrics and logs for a synthetic monitor, see Explore synthetic monitor results.

Before you begin

• 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:

  • Monitoring Editor (roles/monitoring.editor)
  • Cloud Functions Developer (roles/cloudfunctions.developer)

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

  You might also be able to get the required permissions through custom roles or other predefined roles.

• The API instructions on this page are for the APIs Explorer. However, you can also issue a curl command. The APIs Explorer provides the curl syntax.

List synthetic monitors

Console

To list the synthetic monitors in your Google Cloud project, do the following:

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

   Go to Synthetic monitoring

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

2. Optional: To restrict which synthetic monitors are listed, add filters.

   Each filter is composed of a name and a value. You can set the value to be an exact match for an synthetic monitor name or a partial match. Matches aren't case sensitive. For example, to list all synthetic monitors whose name contains default, do the following:

   • Click Filter table and select Display name.
   • Enter default and then press the return key.

   If you have multiple filters, then the filters are automatically joined by a logical AND unless you insert an OR filter. The previous example uses the OR filter so that an uptime check is listed if its name matches default or Testing check.

The Synthetic monitors page displays the following for each synthetic monitor:

• Status of the most recent execution.
• A link to detailed information about that synthetic monitor.
• The success rate and average execution time.
• The number of alerting policies.
• To edit, copy, or delete the synthetic monitor, and to create an alerting policy, use the More options menu.

gcloud

To list your uptime checks and synthetic monitors, run the gcloud monitoring uptime list-configs command:

gcloud monitoring uptime list-configs

The returned data includes the following:

• Name and display name.
• Check identifier.
• Monitored resource.
• Period between checks.

You can configure the Google Cloud CLI command to filter and sort the results.

API

To list the synthetic monitors in your Google Cloud project, including uptime checks, call the projects.uptimeCheckConfigs.list method:

1. Click projects.uptimeCheckConfigs.list.

2. Use the APIs Explorer.

   Set the method's parent to the name of the project, ensure that you use the following format:

   projects/PROJECT_ID
   

   In the previous expression, PROJECT_ID is your Google Cloud project ID.

For a synthetic monitor, the result contains a field labeled syntheticMonitor.

View details of a synthetic monitor

Console

To view the details of a synthetic monitor in your Google Cloud project, do the following:

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

   Go to Synthetic monitoring

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

2. To open the Synthetic monitor details page, locate the synthetic monitor that you want to view, and then click its name.

   If you want to view your Cloud Run function from the Functions details page provided by Cloud Run functions, then select the Code tab and then click the function's name. The Functions details page opens in a new window. The tabs on this page let you view metrics and logs, and configuration information.

gcloud

To list the details of an uptime check or synthetic monitor, run the gcloud monitoring uptime describe command:

gcloud monitoring uptime describe CHECK_ID

Before you run the previous command, replace CHECK_ID with the identifier of the uptime check or synthetic monitor. You can find the identifier by running the gcloud monitoring uptime list-configs command and examining the name field. For more information, see Find the unique identifier of a synthetic monitor.

The data returned for the uptime check includes the following:

• Name and display name.
• Check identifier.
• Monitored resource.
• Period between checks.

API

To list the details of a specific synthetic monitor in your Google Cloud project, call the projects.uptimeCheckConfigs.get method:

1. Click projects.uptimeCheckConfigs.get.

2. Use the APIs Explorer.

   Set the method's parent to the identifier of the synthetic monitor, ensure that you use the following format:

   projects/PROJECT_ID/uptimeCheckConfigs/CHECK_ID
   

   In the previous expression, PROJECT_ID is your Google Cloud project ID and CHECK_ID is the synthetic monitor ID.

   For example, the value of the parent field might be:

   projects/my-project/uptimeCheckConfigs/10863117100295372627
   

   To find the value of the CHECK_ID, you can issue the projects.uptimeCheckConfigs.list method. To reduce the number of returned results, include a filter. For example, add the filter displayName="MySyntheticMonitor".

Edit a synthetic monitor or Cloud Run function

Console

Note: If you only want to modify the Cloud Run function, then you can use the Function details page or the Synthetic monitor details page. In both cases, you must select the edit option, make your changes, and then deploy the modified Cloud Run function.

To edit a synthetic monitor or its Cloud Run function by using the Synthetic monitor details page, do the following:

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

   Go to Synthetic monitoring

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

2. Locate the synthetic monitor that you want to edit, click More options, and then select Edit.

3. Optional: To edit the Cloud Run function, click Edit function, make your changes, and then click Apply function.

   For broken-link checkers, to modify the origin URI or the options that define which links are tested, edit the Cloud Run function, and then update the options object in the index.js file. For information about the fields and syntax for this object, see broken-links-ok/index.js.

4. To retain your modifications, click Save. Otherwise, click Cancel.

gcloud

To modify an uptime check or synthetic monitor, run the gcloud monitoring uptime update command:

gcloud monitoring uptime update CHECK_ID OPTIONAL_FLAGS

Before you run the previous command, do the following:

• Replace CHECK_ID with the identifier of the uptime check or synthetic monitor. You can find the identifier by running the gcloud monitoring uptime list-configs command and examining the name field. For more information, see Find the unique identifier of an uptime check.

• Define which fields that you want to modify. For synthetic monitors, you can only update the following fields:

  • Period
  • Display name
  • Timeout
  • User labels

For example, to set the period of a synthetic monitor to be 10 minutes, run the following command:

gcloud monitoring uptime update CHECK_ID --period=10

API

Alerting policies and functions aren't contained by a synthetic monitor, and therefore they can't be edited by the procedure described in this section:

• To modify an alerting policy, use the Google Cloud console or call the alertPolicies.patch method. For more information, see Manage alerting policies by API.

• To modify a Cloud Run function, after you update the function source you must redeploy the function. For more information, see Deploy a Cloud Run function.

To edit a synthetic monitor, call the projects.uptimeCheckConfigs.patch method:

1. Click projects.uptimeCheckConfigs.patch.

2. Use the APIs Explorer.

   1. Set the method's parent to the identifier of the synthetic monitor, ensure that you use the following format:

      projects/PROJECT_ID/uptimeCheckConfigs/CHECK_ID
      

      In the previous expression, PROJECT_ID is your Google Cloud project ID and CHECK_ID is the synthetic monitor ID.

      To find the value of the CHECK_ID, you can issue the projects.uptimeCheckConfigs.list method. To reduce the number of returned results, include a filter. For example, add the filter displayName="MySyntheticMonitor".

   2. Set the method's query parameter, updateMask, to identify which fields in the object are being modified. For example, to update the value of the displayName, then query parameter is as follows:

      updateMask=displayName
      

Copy a synthetic monitor

Console

To copy a synthetic monitor in your Google Cloud project, do the following:

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

   Go to Synthetic monitoring

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

2. Locate the synthetic monitor that you want to edit, click More options, and then select Copy.

   The Copy Synthetic Check dialog opens with fields pre-populated, including a copy of the Cloud Run function.

3. Click Create function, update the function as necessary, and then click Apply function.

4. To retain your modifications, click Create. Otherwise, click Cancel.

   When you click Create, your Cloud Run function is created and deployed, and then the synthetic monitor is created.

gcloud

There is no Google Cloud CLI method that lets you copy a synthetic monitor.

API

There is no API method that lets you copy a synthetic monitor. However, you can make a copy by performing the following steps:

1. Call the projects.uptimeCheckConfigs.get method and save the response. For more information, see View details of a synthetic monitor.
2. Edit the response.
3. Call the projects.uptimeCheckConfigs.create method and pass to the method the edited response.

Delete a synthetic monitor

Console

Note: When you delete an uptime check or synthetic monitor by using the Google Cloud console, you also delete associated alerting policies. However, deleting a synthetic monitor doesn't delete the Cloud Run function.

To delete a synthetic monitor and any associated alerting policies, do the following:

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

   Go to Synthetic monitoring

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

2. Locate the synthetic monitor that you want to delete, and then click the name.

3. Optional: If you want to delete the Cloud Run function, then then select the Code tab and then click the function's name. The Functions details page opens in a new window.

4. In the Synthetic monitor details page, click Delete, and then complete the dialog.

   You've now deleted the synthetic monitor.

5. To delete the Cloud Run function, go to the Functions details page, click Delete, and then complete the dialog.

gcloud

Note: You can't delete an uptime check or a synthetic monitor by using the Google Cloud CLI or the Cloud Monitoring API when there is an alerting policy associated with that uptime check or synthetic monitor. You must delete the alerting policy first. Deleting a synthetic monitor doesn't delete the Cloud Run function.

To delete an uptime check or synthetic monitor, run the gcloud monitoring uptime delete command:

gcloud monitoring uptime delete CHECK_ID

Before you run the previous command, replace CHECK_ID with the identifier of the uptime check or synthetic monitor. You can find the identifier by running the gcloud monitoring uptime list-configs command and examining the name field. For more information, see Find the unique identifier of a synthetic monitor.

API

Note: You can't delete an uptime check or a synthetic monitor by using the Google Cloud CLI or the Cloud Monitoring API when there is an alerting policy associated with that uptime check or synthetic monitor. You must delete the alerting policy first. Deleting a synthetic monitor doesn't delete the Cloud Run function.

To delete a synthetic monitor and associated alerting policies, call the projects.uptimeCheckConfigs.delete method:

1. Click projects.uptimeCheckConfigs.delete.

2. Use the APIs Explorer.

   Set the method's parent to the identifier of the synthetic monitor, ensure that you use the following format:

   projects/PROJECT_ID/uptimeCheckConfigs/CHECK_ID
   

   In the previous expression, PROJECT_ID is your Google Cloud project ID and CHECK_ID is the synthetic monitor ID.

   To find the value of the CHECK_ID, you can issue the projects.uptimeCheckConfigs.list method. To reduce the number of returned results, include a filter. For example, add the filter displayName="MySyntheticMonitor".

Find the unique identifier of a synthetic monitor

When your synthetic monitor is created, Monitoring assigns it an identifier. This identifier is embedded in the resource name for the synthetic monitor and has the form:

projects/PROJECT_ID/uptimeCheckConfigs/CHECK_ID

The CHECK_ID is included in the response of the Google Cloud CLI and Cloud Monitoring API methods that create or list synthetic monitors.

What's next

• Create a synthetic monitor
• Explore synthetic monitor results