Naming conventions

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

  • An identifier for a specific project
  • A marker that indicates 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/antho/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 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 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 Anthos, 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 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 User-defined custom 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 identifies a Google Cloud product, such as compute for Compute Engine.
2 PATH identifies the metric within the product, such as instance/cpu/utilization.

Naming metric types and labels

If you are creating custom metric types, you must adhere to the following rules for naming your metric types and labels. When defining a metric type, labels are specified as key-value pairs of type LabelDescriptor. The key acts as the name of the label.

  • Metric types
    • You can use upper and lower-case letters (A-Z, a-z), digits (0-9), and underscores (_) in the string.
    • You can use periods (.) only in the domain part of the string, for example, custom.googleapis.com.
    • You can use forward slashes (/) to separate path elements.
    • You can start each path element with a letter or digit.
    • The maximum length of a metric-type string is 200 characters.
  • Label keys
    • You can use lower-case letters (a-z), digits (0-9), underscores (_), and dashes (-) in a label key.
    • You can 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 10 labels per metric type.