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, which is always a Google Cloud project.
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 thecurl
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.
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.
Add a project to a metrics scope
If you are using App Hub, then to view system metrics from App Hub, you must configure both the App Hub host project and the metrics scope. Adding an App Hub service project to an App Hub host project doesn't modify the project's metrics scope. Similarly, adding a project to a metrics scope doesn't modify the list of App Hub service projects attached to the App Hub host project. For information about configuring an App Hub host project, see Add or remove service projects.
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
If you are using App Hub, then before you remove a project from the metrics scope ensure that the project isn't being used by an App Hub application. Removing the project from the metrics scope won't affect the application. However, you won't be able to view system metrics for that application from the context of the App Hub host project. For information about configuring an App Hub host project, see Add or remove service projects.
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.
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 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" } }
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 contains an
@type
field.
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.
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
isfalse
, the operation is in progress.To refresh the status information, send a
GET
request to theoperation.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 theOperation.name
field.When
done
istrue
, the operation is complete and either theerror
orresponse
field is set:error
: When set, the asynchronous operation failed. The value of this field is aStatus
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: