Using custom metrics

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

  • Custom metrics with OpenCensus describes how to use OpenCensus, an open-source monitoring and tracing library, to create custom metrics, add metric data to them, and export them to Cloud Monitoring.

    When metrics from OpenCensus are exported to Cloud Monitoring, Monitoring treats them like any other custom metrics.

  • Creating custom metrics describes how to use the Cloud Monitoring API to create custom metrics and to add time series data to them.

    The Monitoring API is illustrated with examples using the APIs Explorer, C#, Go, Java, Node.js, PHP, Python, and Ruby programming languages.

The following information applies to both custom metrics and the metrics provided by Cloud Monitoring:

  • Browsing metrics explains how to list and examine your custom metrics and more than 1,500 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 Cloud Monitoring API v3. See Introduction to the Cloud Monitoring API for reference documentation.

For a discussion of concepts underlying metrics in Cloud Monitoring, see Metrics, time series, and resources.

Before you begin

Create or select a Google Cloud Console project whose monitoring data you want to access.

In this guide, the ID for your project is referred to as {your-project-id}. If you want to set up metrics based on the logs in your Google Cloud 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 Google Cloud projects.
  • Custom metric names typically begin, which differs from the built-in metrics.
  • You can write time series data to your custom metrics.
  • You can delete your custom metrics.

See the Metrics list for details about the built-in metrics.

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

Monitoring 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 Quotas and limits for limits related to custom metrics and data retention. 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.