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 Monitoring API. You can also use metric data in charts and alerts.

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

Before you begin

Custom metrics are a paid feature of Monitoring and there could be costs for your custom metrics. For more information on pricing, see Stackdriver Pricing.

Custom metrics reside in GCP Console projects that are members of a Workspace. 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 Monitoring.

If you are looking to setup metrics based on Stackdriver logs in your GCP projects, use logs-based metrics.

About custom metrics

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

  • You can create custom metrics within your GCP 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:

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 Cloud Storage or BigQuery.

For information about latencies associated with writing data to custom metrics, see Latency of metric data.

Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Monitoring