This page explains how to use the Monitoring API to do the following:
- Get a list or description of your custom metric types.
- Get a list or description of built-in metric types, which can help you design your custom metrics. This list also appears in the documentation; see Metrics list.
- Get a list or description of the available monitored resource types, which you can use to label your custom metrics' time series data. This list also appears in the documentation; see Monitored resource list.
For an introduction to these concepts, see Metrics, time series, and resources.
This page describes the metricDescriptors.list
and get
methods, and the
monitoredResourceDescriptors.list
and get
methods.
There are several ways to use these methods:
To run the methods without writing any code, the examples in the PROTOCOL tabs on this page use the forms-based API Explorer. (See API Explorer for more information on this tool.)
To learn how to use the methods from selected programming languages, see the runnable code samples on this page.
Browsing metrics from BindPlane
Metrics from BindPlane can be found in Metrics Explorer.
All BindPlane metrics are shown with a resource type of generic_node
, and
the metric name is prefixed with
external.googleapis.com/bluemedora/generic_node/
.
For information about the available sources in BindPlane, refer to the BindPlane Sources documentation.
Workspace not required
Except when working with custom metrics, you can use any existing project in
metricDescriptors.list
and
get
invocations,
even if the project is not in a Workspace. If you are working with custom
metrics, then you must specify the project where the custom metrics are defined.
You can also use any existing project with the
monitoredResourceDescriptors.list
and
get
methods.
Listing metric descriptors
Metric descriptors are the schemas that define built-in and custom metrics. By browsing the available metric descriptors, you can find out details about the metrics you're interested in.
There are presently over 900 built-in metrics; see the complete Metrics list for reference.
For more information on how metric types are named, see Naming conventions.
Example: Listing metric types
To get a current list of metric types, use the
metricDescriptors.list
method.
To narrow the set of metric types that are returned, use a filter. See
Value types and metric kinds for help deciding which
metric types to search for.
Protocol
The following are sample parameters to
metricDescriptors.list
for returning Compute Engine metrics:
- name:
projects/[PROJECT_ID]
- filter:
metric.type = starts_with("compute.googleapis.com")
- fields:
metricDescriptors.type,metricDescriptors.displayName
Before clicking the Execute button, change [PROJECT_ID]
to a valid ID.
The following sample output shows three of the many Compute Engine metrics that match the filter:
"metricDescriptors": [
{
"displayName": "Dropped bytes",
"type": "compute.googleapis.com/firewall/dropped_bytes_count"
},
{
"displayName": "Dropped packets",
"type": "compute.googleapis.com/firewall/dropped_packets_count"
},
{
"displayName": "Reserved cores.",
"type": "compute.googleapis.com/instance/cpu/reserved_cores"
},
...
]
The type
value here 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”.
C#
Go
Java
Node.js
PHP
Python
Ruby
See Troubleshooting API calls if you have difficulty.
Example: Getting metric descriptors
To get more details about a metric type, retrieve the full metric descriptor
using the metricDescriptors.get
method.
To retrieve a specific metric descriptor, you need the full name of the descriptor. This value 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 Example: Listing metric types for more on thetype
value.
Example: projects/[PROJECT_ID]/metricDescriptors/compute.googleapis.com/firewall/dropped_packets_count
.
Protocol
To get the details of Compute Engine's /firewall/dropped_packets_count
metric,
use the following parameter to
metricDescriptors.get
:
- name:
projects/[PROJECT_ID]/metricDescriptors/compute.googleapis.com/firewall/dropped_packets_count
Before clicking the Execute button, change [PROJECT_ID]
to a valid ID.
The following sample response shows the metric's descriptor:
{
"type": "compute.googleapis.com/firewall/dropped_packets_count",
"name": "projects/[PROJECT_ID]/metricDescriptors/compute.googleapis.com/firewall/dropped_packets_count",
"description": "Delta count of incoming packets dropped by the firewall.",
"displayName": "Dropped packets",
"labels": [
{
"key": "instance_name",
"description": "The name of the VM instance."
}
],
"metricKind": "DELTA",
"valueType": "INT64",
"unit": "1"
}
C#
Go
Java
Node.js
PHP
Python
Ruby
See Troubleshooting API calls if you have difficulty.
Listing monitored resources
Monitored resources are cloud entities that can be monitored. By browsing the existing monitored resource types, you can find the kinds of entities that have metrics.
There are presently about 100 different monitored resource descriptors; see the Monitored resource list for the full set.
For an introduction to metric descriptors and monitored resources, see Metrics, time series, and resources.
You can use any existing project in
monitoredResourceDescriptors.list
and
get
invocations,
even if the project is not in a Workspace.
Example: Listing 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
To get a current list of monitored resource types,
use monitoredResourceDescriptors.list
with the following sample parameters:
- name:
projects/[PROJECT_ID]
- fields:
resourceDescriptors.type
Before clicking the Execute button, change [PROJECT_ID]
to a valid ID.
The following sample response shows some of the returned monitored resource types:
{
"resourceDescriptors": [
{
"type": "api"
},
{
"type": "aws_cloudfront_distribution"
},
{
"type": "aws_dynamodb_table"
},
{
"type": "aws_ebs_volume"
},
...
}
C#
Go
Java
Node.js
PHP
Python
Ruby
See Troubleshooting API calls if you have difficulty.
Getting resource descriptors
To get more details about a monitored-resource type, retrieve the full
descriptor using the monitoredResourceDescriptors.get
method.
To retrieve a specific monitored resource descriptor, you need the full name of the descriptor. This value is constructed from two components:
- A prefix consisting of
projects/[PROJECT_ID]/monitoredResourceDescriptors
. - The
type
value that identifies the metric descriptor, for example,gce_instance
. See the PROTOCOL tab in Example: Listing resource types for more on thetype
value.
Example: projects/[PROJECT_ID]/monitoredResourceDescriptors/gce_instance
.
Protocol
To get the details of the gce_instance
resource type, use the following
parameter to
monitoredResourceDescriptors.get
method:
- name:
projects/[PROJECT_ID]/monitoredResourceDescriptors/gce_instance
Before clicking the Execute button, change [PROJECT_ID]
to a valid ID.
The following sample response shows the descriptor for this monitored resource:
{
"type": "gce_instance",
"displayName": "GCE VM Instance",
"description": "A virtual machine instance hosted in Google Compute Engine (GCE).",
"labels": [
{
"key": "project_id",
"description": "The identifier of the GCP 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"
}
C#
Go
Java
Node.js
PHP
Python
Ruby
See Troubleshooting API calls if you have difficulty.
Finding resources
Monitored resource objects are included in time series data. You can usually
guess which metrics include monitored resources of specific types. For example,
if you want to see a gce_instance
monitored resource, look at time series data
from a metric like compute.googleapils.com/instance/cpu/utilization
. After
you've identified a likely metric time series, see
Reading metric data.