This document explains how to use the Cloud Monitoring API to get lists or descriptions of the following:
- User-defined metric types defined in your project.
- Third-party metric types with time-series data in your project.
Metrics generated by BindPlane
are examples of third-party metrics. BindPlane metrics
have a prefix of
workload.googleapis.com/3rd-party-app-name/
. For a full list of supported third-party application metrics, see the BindPlane Sources documentation. - Built-in metric types provided by Google Cloud. These metric types can help you design your user-defined metrics. You can also find information about these metrics in the documentation; see Metrics list.
- Monitored resource types available to your project. You can also find information about these resources in the documentation; see Monitored resource list.
To run the methods without writing any code, the examples in the Protocol tabs on this page use the forms-based APIs Explorer. (See APIs Explorer for more information about this tool.)
To learn how to use the methods from selected programming languages, see the runnable code samples on this page.
Before you begin
- For an introduction to metrics and monitored resources, see Metrics, time series, and resources.
List metric descriptors
Metric descriptors are the schemas that define metrics. To find details about the metrics you're interested in, browse the available metric descriptors:- Built-in metrics: You can issue API requests to any existing project, or you can use Metrics lists documentation.
- User-defined and external metrics: You must issue the API request to a project where the user-defined metric is defined or where time-series data for the metric exists.
For more information on how metric types are named, see Naming conventions.
List metric types
To get a current list of metric descriptors, use the
metricDescriptors.list
method.
To narrow the set of metric types that are returned, use a filter.
For help deciding which metric types to search for, see
Value types and metric kinds.
Protocol
Open the
metricDescriptors.list
reference page.In the pane labeled Try this method, enter the following:
- name:
projects/PROJECT_ID
. ReplacePROJECT_ID
with the ID of your Google Cloud project. - filter:
metric.type = starts_with("compute.googleapis.com")
- name:
Click Execute.
The following sample response shows some of the retrieved metric descriptors:
"metricDescriptors": [ { "name": "projects/PROJECT_ID/metricDescriptors/compute.googleapis.com/firewall/dropped_bytes_count", "labels": [{...}], ... "description": "Count of incoming bytes dropped by the firewall.", "displayName": "Dropped bytes", "type": "compute.googleapis.com/firewall/dropped_bytes_count", ... }, { "name": "projects/PROJECT_ID/metricDescriptors/compute.googleapis.com/firewall/dropped_packets_count", "labels": [{...}], ... "description": "Count of incoming packets dropped by the firewall.", "displayName": "Dropped packets", "type": "compute.googleapis.com/firewall/dropped_packets_count", }, ... ]
The type
value in each descriptor identifies the metric descriptor, for
example, compute.googleapis.com/firewall/dropped_packets_count
. This value is
sometimes also called the “metric type” or the
“metric type name”.
To view the request as a curl
command, as an
HTTP request, or in JavaScript, click fullscreen Full screen
in APIs Explorer.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
If you have difficulty, see Troubleshooting API calls.
Get metric descriptors
To get information about a single metric type, use the
metricDescriptors.get
method.
This method returns a metric descriptor.
To retrieve a specific metric descriptor, you must provide the full name of the metric to the API. The full name is constructed from two components:
- A prefix consisting of
projects/PROJECT_ID/metricDescriptors
. - The
type
value that identifies the metric descriptor, for example,compute.googleapis.com/firewall/dropped_packets_count
. See the Protocol tab in List metric types for more on thetype
value.
The following is an example of the full name of a metric:
projects/PROJECT_ID/metricDescriptors/compute.googleapis.com/firewall/dropped_packets_count
Protocol
To get the descriptor for the Compute Engine /firewall/dropped_packets_count
metric, do the following:
Open the
metricDescriptors.list
reference page.In the pane labeled Try this method, enter the following:
name:
projects/PROJECT_ID/metricDescriptors/compute.googleapis.com/firewall/dropped_packets_count
Replace
PROJECT_ID
with the ID of your Google Cloud project.
Click Execute.
The following sample response shows the metric's descriptor:
{ "name": "projects/PROJECT_ID/metricDescriptors/compute.googleapis.com/firewall/dropped_packets_count", "labels": [ { "key": "instance_name", "description": "The name of the VM instance." } ], "metricKind": "DELTA", "valueType": "INT64", "unit": "1", "description": "Count of incoming packets dropped by the firewall.", "displayName": "Dropped packets", "type": "compute.googleapis.com/firewall/dropped_packets_count", }
To view the request as a curl
command, as an
HTTP request, or in JavaScript, click fullscreen Full screen
in APIs Explorer.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
If you have difficulty, see Troubleshooting API calls.
List monitored resources
Monitored resources are cloud entities that can be monitored. To find the kinds of entities that have metrics, browse the list of monitored resource types.
To get information about monitored resources, you can issue API requests to any existing project, or you can use the Monitored resource list documentation.
List resource types
To get a current list of monitored resource types from the
Monitoring API,
use the monitoredResourceDescriptors.list
method and supply your project ID.
Protocol
Open the
monitoredResourceDescriptors.list
reference page.In the pane labeled Try this method, enter the following:
- name:
projects/PROJECT_ID
. ReplacePROJECT_ID
with the ID of your Google Cloud project.
- name:
Click Execute.
The following sample response shows some of the returned monitored resource types:
{ "resourceDescriptors": [ { "type": "aiplatform.googleapis.com/Endpoint", "displayName": "AI Platform Endpoint", "description": "A Cloud AI Platform API Endpoint where Models are deployed into it.", "labels": [{...}], "name": "projects/PROJECT_ID/monitoredResourceDescriptors/aiplatform.googleapis.com/Endpoint", }, { "type": "aiplatform.googleapis.com/Featurestore", "displayName": "AI Platform Feature Store", "description": "A Cloud AI Platform Feature Store.", "labels": [{...}], "name": "projects/PROJECT_ID/monitoredResourceDescriptors/aiplatform.googleapis.com/Featurestore", },
To view the request as a curl
command, as an
HTTP request, or in JavaScript, click fullscreen Full screen
in APIs Explorer.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
If you have difficulty, see Troubleshooting API calls.
Getting resource descriptors
To get a specific monitored-resource descriptor, use the
monitoredResourceDescriptors.get
method.
To retrieve a specific monitored-resource descriptor, you must provide the full name of the descriptor to the API. The full name is constructed from two components:
- A prefix consisting of
projects/PROJECT_ID/monitoredResourceDescriptors
. - The
type
value that identifies the monitored-resource descriptor, for example,gce_instance
. See the Protocol tab in List resource types for more on thetype
value.
The following is an example of the full name of a monitored resource:
projects/PROJECT_ID/monitoredResourceDescriptors/gce_instance
Protocol
To get the descriptor for the gce_instance
resource type, do the following:
Open the
monitoredResourceDescriptors.get
reference page.In the pane labeled Try this method, enter the following:
name:
projects/PROJECT_ID/monitoredResourceDescriptors/gce_instance
Replace
PROJECT_ID
with the ID of your Google Cloud project.
Click Execute.
The following sample response shows the descriptor for this monitored resource:
{ "type": "gce_instance", "displayName": "VM Instance", "description": "A virtual machine instance hosted in Compute Engine.", "labels": [ { "key": "project_id", "description": "The identifier of the Google Cloud project associated with this resource, such as \"my-project\"." }, { "key": "instance_id", "description": "The numeric VM instance identifier assigned by Compute Engine." }, { "key": "zone", "description": "The Compute Engine zone in which the VM is running." } ], "name": "projects/PROJECT_ID/monitoredResourceDescriptors/gce_instance" }
To view the request as a curl
command, as an
HTTP request, or in JavaScript, click fullscreen Full screen
in APIs Explorer.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
If you have difficulty, see Troubleshooting API calls.
What's next
- For information about how to use the Cloud Monitoring API to read time-series data, see Retrieve time-series data.
- For a list of monitored-resource types available for your use with user-defined metrics, see Choose a monitored-resource type.