Configure a metrics scope by using the API

This document describes how to use the Google Cloud CLI or the Cloud Monitoring API to configure the metrics scope of a Google Cloud project. This page is intended for developers and system administrators.

The commands on this page refer to a "resource container". While a resource container can be an organization, folder, or project, the commands described on this page only support Google Cloud projects.

Before you begin

If you aren't familiar with the terms metrics scope and scoping project, then see Metrics scopes.
Ensure that your Identity and Access Management (IAM) roles on the scoping project and on each project that you want to add as a monitored project include all permissions in the Monitoring Admin (roles/monitoring.admin) role. For more information, see Metrics scope configurations.
The metrics scope methods of the Cloud Monitoring API that retrieve information are synchronous; however, those APIs that change state are asynchronous. The Google Cloud CLI commands block until the asynchronous operation completes. For information about how to determine when an asynchronous API method is complete and how to determine its status, see Asynchronous API methods.
If you plan to invoke the Cloud Monitoring API by using curl or if you want to use the samples on this page, then complete the curl command setup steps.

List all metrics scopes that include a project

gcloud

To get a list of metrics scopes that can view the metrics for a resource container, such as a Google Cloud project, run the gcloud beta monitoring metrics-scopes list command:

gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME

Before you run the command, enter the identifier of the resource container into the variable MONITORED_RESOURCE_CONTAINER_NAME. When the resource container is a Google Cloud project, enter projects/PROJECT_ID_OR_NUMBER.

For example, to list the metrics scopes that include the project my-project, run the following command:

gcloud beta monitoring metrics-scopes list projects/my-project

The following response indicates that the project my-project is included in two metrics scopes:

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

To get detailed information about a metrics scope, run the gcloud beta monitoring metrics-scopes describe command.

curl

To get a list of metrics scopes that can view the metrics for a project, send a GET request to the locations.global.metricsScopes.listMetricsScopesByMonitoredProject endpoint and include the query parameter that specifies the project.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

When successful, the response is an array of MetricsScope objects.

This method doesn't result in an entry being written to the audit logs of the scoping project. To have these actions recorded in the audit log, enable Data Read for the Cloud Resource Manager API. For more information, see Configuring Data Access audit logs.

Get details about a metrics scope

gcloud

To get detailed information about a metrics scope, run the gcloud beta monitoring metrics-scopes describe command:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

Before you run the command, enter the name of the fully qualified name of a metrics scope into the variable METRICS_SCOPE_ID. The following is an example of a fully qualified name:

locations/global/metricsScopes/012345012345

The following is an example of response. In this example, the metrics scope contains one project, and the ID of the metrics scope and project are the same:

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

To identify the Google Cloud project from its ID, run the gcloud projects list command and filter by the project ID. For example, to get the name for the project 012345012345, run the following command:

gcloud projects list --filter="012345012345" -format="value(NAME)"

curl

To get information about a metrics scope, send a GET request to the locations.global.metricsScopes.get endpoint:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

When successful, the response is a MetricsScope object.

Add a project to a metrics scope

gcloud

To add a resource container, such as Google Cloud project, to a metrics scope, run the gcloud beta monitoring metrics-scopes create command:

gcloud beta monitoring metrics-scopes create MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

Before you run the previous command, do the following:

Enter the name or ID of the Google Cloud project whose metrics scope is to be modified into the variable SCOPING_PROJECT_ID_OR_NUMBER.
Enter the identifier of your resource container into the variable MONITORED_RESOURCE_CONTAINER_NAME. When the resource container is a Google Cloud project, enter projects/PROJECT_ID_OR_NUMBER.

For example, the following command adds the project my-monitored-project to the metrics scope of the project named my-staging-projects:

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

The response to the previous command provides confirmation that the command completed successfully:

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

To add a Google Cloud project to a metrics scope, send a POST request to the locations.global.metricsScopes.projects.create endpoint. In the following example, the project identified by the environment variable MONITORED_PROJECT_ID_OR_NUMBER is added as monitored project:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

The response of this asynchronous method is an Operation object.

Applications calling this method should poll the operation.get endpoint until the value of the Operation.done field is true. When the Operation.done field is set to false, that indicates the operation is in progress. For more information, see Asynchronous API commands.

The following is an example of the response when adding a monitored project is successful:

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "GCP",
    "providerAccountId": "...",
    ...
  }
}

In the previous response, the Operation.done field is set to true. This value indicates that the command is complete. Because the command completed successfully, the Operation.response field is set and its value is a MonitoredProject object. The response.name field includes the identifier of the scoping project and the monitored project. The providerAccountId field lists the name of the monitored project.

Invoking this method results in an entry in the audit logs of the scoping project. The Google Cloud console doesn't invoke this API method. Therefore, modifications made to a metrics scope when using the Google Cloud console aren't recorded in the audit logs.

Remove a project from a metrics scope

gcloud

To remove a resource container, such as a Google Cloud project, from a metrics scope, run the gcloud beta monitoring metrics-scopes delete command:

gcloud beta monitoring metrics-scopes delete MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

Before you run the previous command, do the following:

Enter the name or ID of the Google Cloud project whose metrics scope is to be modified into the variable SCOPING_PROJECT_ID_OR_NUMBER.
Enter the identifier of your resource container into the variable MONITORED_RESOURCE_CONTAINER_NAME. When the resource container is a Google Cloud project, enter projects/PROJECT_ID_OR_NUMBER.

For example, the following command removes the project my-monitored-project from the metrics scope of the project named my-staging-projects:

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

The response to the previous command provides confirmation that the command completed successfully:

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

The following error is reported when the scoping project isn't monitoring the project specified by the MONITORED_RESOURCE_CONTAINER_NAME variable:

NOT_FOUND: Requested entity was not found.

curl

To remove a Google Cloud project from a metrics scope, send a DELETE request to the locations.global.metricsScopes.projects.delete endpoint:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

The response to this asynchronous method is an Operation object.

The following is an example of the response when removal of a monitored project is successful:

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Asynchronous API methods

All metrics scope methods of the Cloud Monitoring API that change the state of the system, for example, the command to add a monitored project a metrics scope, are asynchronous. For these commands, the command response is an Operation object.

Applications that call an asynchronous API method should poll the operation.get endpoint until the value of the Operation.done field is true:

When done is false, the operation is in progress.

To refresh the status information, send a GET request to the operation.get endpoint:
```
curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/${OPERATION_NAME}
```
In the previous command, OPERATION_NAME is an environment variable that stores the value of the Operation.name field.
When done is true, the operation is complete and either the error or response field is set:
- error: When set, the asynchronous operation failed. The value of this field is a Status object that contains a gRPC error code and an error message.
- response: When set, the asynchronous operation completed successfully, and the value reflects the result.

`curl` command setup

This section describes the setup used to create the curl commands in this document. Each curl command on this page includes a set of arguments followed by the URL of an API resource:

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

Set these environment variables to simplify creation of the curl commands:

Create the environment variable to store the scoping project ID or number:
```
SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER
```
Optional. If you plan to add or remove monitored projects, then configure the environment variable with the monitored project ID or number:
```
MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER
```
Authenticate to the Google Cloud CLI:
```
gcloud auth login
```
Optional. To avoid having to specify your project ID with each gcloud command, set your project ID as the default by using gcloud CLI:
```
gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
```
Create an authorization token and capture it in an environment variable:
```
TOKEN=`gcloud auth print-access-token`
```
Tokens are valid for a limited time. If commands that worked suddenly report that you are unauthenticated, then reissue this command.
To verify that you got an access token, echo the TOKEN variable:
```
echo ${TOKEN}
ya29.GluiBj8o....
```

You might also have to specify other arguments, for example, to specify the type of the HTTP request (for example, -X DELETE). The default request is GET, so the examples don't specify it.

What's next

For information about using Google Cloud with Terraform, see the following resources:

Configure a metrics scope by using the API

Before you begin

List all metrics scopes that include a project

gcloud

curl

Get details about a metrics scope

gcloud

curl

Add a project to a metrics scope

gcloud

curl

Remove a project from a metrics scope

gcloud

curl

Asynchronous API methods

curl command setup

What's next

`curl` command setup