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
agent.googleapis.com/[SERVICE]1/[PATH]2 Metrics from the Monitoring agent
aws.googleapis.com/[SERVICE]1/[PATH]2 Metrics from Amazon Web Services
istio.io/[PATH]2 Metrics from Istio
kubernetes.io/anthos/[PATH]2 Metrics from Anthos
logging.googleapis.com/[PATH]2 Logs-based metrics from Cloud Logging
custom.googleapis.com/[PATH]2 User-defined custom metrics
external.googleapis.com/[EXT_SERVICE]/[PATH]2
external.googleapis.com/prometheus/[PATH]2
Third-party custom metrics3
Example: Prometheus metrics

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.
3 Google Cloud also supports several sets of well-known third-party metric types. Some, like those for Istio and Kubernetes (available as Anthos metrics) are treated like other built-in metric types. Others, like Knative and Netapp.com, are treated like user-defined custom metric types.

Cloud Monitoring defines the metric types in the first three rows of the table. These are the metric types that appear in the Metrics list. You can use these metric types, and the Anthos metric types, in any Google Cloud project.

The last three rows list custom and third-party metric types. You can use these metric types only in the projects where you define or import them. For more information on custom metric, see Using custom metrics.

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.