Metric naming conventions

This document describes the naming conventions Cloud Monitoring enforces for metrics.

Metric resource name

The resource name for a metric type consists of a string with three primary sub-structures:

  • An identifier for a specific project.
  • A marker, which is always set to metricDescriptors, to indicate that the string represents a metric descriptor.
  • The metric type.

Resource names for metric types follow this pattern:

projects/PROJECT_ID/metricDescriptors/METRIC_TYPE

The sub-string METRIC_TYPE is an identifier that represents the metric type. It comes in a variety of formats, for example:

agent.googleapis.com/agent/api_request_count
compute.googleapis.com/firewall/dropped_bytes_count
istio.io/service/client/received_bytes_count
kubernetes.io/anthos/APIServiceOpenAPIAggregationControllerQueue1_adds

In the metric descriptor, the name field stores the metric type's resource name, and the type field stores the METRIC_TYPE sub-string.

The following table shows how to parse the METRIC_TYPE sub-strings contained in a resource name:

Possible structures Description
SERVICE_NAME 1.googleapis.com/PATH 2 Metrics from Google Cloud products and services. For a full list of these metrics, see Google Cloud metrics.
agent.googleapis.com/SERVICE_NAME 1/PATH 2 Metrics from the Monitoring and Logging agents running on VM instances in Google Cloud or AWS. For a full list of these metrics, see Agent metrics.
kubernetes.io/anthos/PATH 2 Metrics from GKE Enterprise, a Google Cloud service that enables you to run Kubernetes clusters both on-prem and in the cloud. For a full list of these metrics, see Anthos metrics.
aws.googleapis.com/SERVICE_NAME 1/PATH 2 Metrics from Amazon Web Services. For a full list of these metrics, see AWS metrics.
istio.io/PATH 2 Metrics from Istio for Google Cloud. For a full list of these metrics, see Istio metrics.
kubernetes.io/PATH 2 Metrics from Google Kubernetes Engine. For a full list of these metrics, see Kubernetes metrics.
knative.dev/PATH 2 Metrics from Knative. For a full list of these metrics, see Knative metrics.
external.googleapis.com/EXT_SERVICE/PATH 2
external.googleapis.com/prometheus/PATH 2		 Third-party custom metrics such as Prometheus. This open-source monitoring tool is often used with Kubernetes. For more information about these metrics, see External metrics. You can use these metric types only in the projects that define them.
custom.googleapis.com/PATH 2
external.googleapis.com/user/PATH 2		 User-defined metrics. You can use these metric types only in the projects where you define them.
logging.googleapis.com/PATH 2 Logs-based metrics from Cloud Logging. You can use predefined metrics or you can create custom metrics. Custom metrics can only be used in projects where you define them.

1 SERVICE_NAME identifies a Google Cloud product, such as compute for Compute Engine.
2 PATH identifies the metric within the product, such as instance/cpu/utilization.

Rules for metric types and labels

This list contains rules to follow when you create custom metric types. Labels associated with a metric type are specified as key-value pairs of type LabelDescriptor. The key acts as the name of the label.

  • Metric types

    • Use upper and lower-case letters (A-Z, a-z), digits (0-9), periods (.), and underscores (_) in the string.
    • Use forward slashes (/) to separate path elements.
    • You must start each path element with a letter or digit.
    • The maximum length of a metric-type string is 200 characters.

  • Label keys

    • Use lower-case letters (a-z), digits (0-9), and underscores (_) in a label key.
    • You must start label keys with a letter.
    • The maximum length of a label key is 100 characters.
    • Each key must be unique within the metric type.
    • You can have no more than 30 labels per metric type.