Using Custom Metrics

This guide describes how to create and use custom metrics. The information is divided into the following sections:

  • Creating custom metrics describes how to create custom metrics and how to add time series data to them.
  • Browsing metrics explains how to list and examine your custom metrics and the over 900 built-in metrics.
  • Reading metrics explains how to retrieve time series data from custom and built-in metrics using the Stackdriver Monitoring API. You can also use metric data in charts and alerts.

All of these operations on metrics require the Stackdriver Monitoring API v3, and are illustrated with examples using the APIs Explorer, C#, Go, Java, Node.js, PHP, Python, and Ruby programming languages. For a discussion of concepts underlying metrics in Stackdriver Monitoring, see Metrics.

Before you begin

Custom metrics are a paid feature of Stackdriver Monitoring and there could be costs for your custom metrics. For more information, see Stackdriver Pricing. You can try out this and other Stackdriver premium features free for 30 days, when you create a new Stackdriver account.

Custom metrics reside in Cloud Platform Console projects that are members of a Stackdriver account. Even if you are only browsing the built-in metrics, you need a project to work from:

  1. Create or select a Google Cloud Platform Console project whose monitoring data you want to access. In this guide, the ID for your project is referred to as {your-project-id}.
  2. Enable your project for Stackdriver Monitoring.

About custom metrics

Custom metrics are the same as Stackdriver Monitoring's built-in metrics, except:

  • You can create custom metrics within your Cloud Platform Console projects.
  • Custom metric names begin custom.googleapis.com/, which is different from the built-in metrics.
  • You can write time series data to your custom metrics.
  • You can delete your custom metrics.

The following table shows which API methods can be used with custom metrics and with built-in metrics:

Stackdriver Monitoring API API method Use with
custom metrics
Use with
built-in metrics
monitoredResourceDescriptors.get yes yes
monitoredResourceDescriptors.list yes yes
metricDescriptors.get yes yes
metricDescriptors.list yes yes
timeSeries.list yes yes
timeSeries.create yes
metricDescriptors.create yes
metricDescriptors.delete yes

Limits and latencies

See Quota policy for limits on the number of custom metrics and the number of active time series, and for the data retention period. If you wish to keep your metric data beyond the retention period, you must manually copy the data to another location, such as Google Cloud Storage or Google BigQuery.

For information about latencies associated with writing data to custom metrics, see Collection, retention, and latency.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Stackdriver Monitoring