Structure of Metric Types

This page provides detailed information about the Monitoring concepts of metric, time series, and monitored resource.

Overview

A metric is a measurement of some characteristic of your cloud application. For example, Monitoring has metrics for the CPU utilization of your VM instances, the number of tables in your SQL databases, and hundreds more.

A metric's measurement is not a single value, because metric values come from many sources and at many times. For example, the CPU utilization metric has measurements from different VM instances, taken at different times. Therefore, Monitoring organizes metrics and their values in the following ways:

• Metric type. Each metric has a metric type name, such as the following:

  compute.googleapis.com/instance/cpu/utilization
  custom.googleapis.com/acme_purple_plates_inc/daily_sales
  

  In Monitoring, the term "metric" almost always means "metric type." There are more than a thousand predefined metric types. You can also create your own custom metrics.

• Time series. Monitoring organizes metric data into time series (plural). Each time series (singular) holds the metric's measurements from a single source. For example, one time series might contain CPU utilization measurements taken from a single VM instance every minute over the last six weeks. If you have hundreds of running VM instances, then your single CPU utilization metric type has hundreds of time series.

• Monitored resource. The source of a time series is represented as a monitored resource, which identifies a particular VM instance, database, or other entity. Monitoring has a few dozen monitored resource types, but it has millions of monitored resources at any instant.

• Metric labels. Some metric types have labels to record additional information about their measurements. For example, a single VM instance can have many CPU cores, so it might make sense to include the CPU core number in the CPU utilization metric. Every different label value has a separate time series. For example, there is a time series for CPU #1 of VM instance A, one for CPU #2 of VM instance A, one for CPU #1 of VM instance B, and so on.

• Aggregation. You can retrieve individual time series for any metric, but you can also aggregate time series to get summary information. For example, you can get a time series of the average CPU utilization of VM instance A by averaging the time series of CPU #1 and CPU #2.

Monitored Resources

A monitored resource (type MonitoredResource) is a structured name that identifies an entity known to Monitoring. Examples of monitored resources include Compute Engine VM instances, Amazon RDS databases, Cloud Storage buckets, and so on. For example, here is the monitored resource for a Compute Engine VM instance:

{ "type": "gce_instance",
  "labels": { "instance_id": "12345678901234",
              "zone": "us-central1-a" }}

One use for monitored resources is to identify the source of metric data sent to Monitoring.

The type of a monitored resource—gce_instance, in the preceding example—is defined by a monitored resource descriptor (type MonitoredResourceDescriptor).

For a complete list of the monitored resource types, see Monitored Resource List.

Metrics

A metric type is defined by a metric descriptor (type MetricDescriptor). The metric descriptor contains the metric type's name, the datatype of its measurements, the labels it uses, and other information. The descriptor does not specify the possible sources or label values associated with the metric type's measurements.

For a complete list of the predefined metric types, see Metrics List.

You can create your own metric descriptors for custom metrics. For more information, see Using Custom Metrics.

Kinds of metrics

Each measurement in a metric is a data point consisting of the metric's value and a time interval. The metric's value type (type ValueType) can be Boolean, integer, floating-point, string, money, or a Distribution.

Each metric also has a metric kind (type MetricKind):

• In a GAUGE metric, each data point represents an instantaneous measurement of a varying value. For example, the current temperature would be a gauge metric.
• In a DELTA metric, each data point represents the change in a value over the time interval. For example, the number of service requests received since the previous measurement would be a delta metric.
• In a CUMULATIVE metric, each data point is a value being accumulated over time. For example, the total number of incoming requests since a service was started would be a cumulative metric.

The following table lists the permitted combinations of metric kinds and value types:

Value type	GAUGE	DELTA	CUMULATIVE^2
BOOL	yes	no	no
INT64	yes	yes^1	yes
DOUBLE	yes	yes^1	yes
STRING	yes^1	no	no
DISTRIBUTION	yes	yes^1	yes
MONEY	no	no	no

¹ This combination is not permitted in custom metrics.
² Cumulative metrics cannot be used directly for charting or alerting in Monitoring, but they can be aggregated into non-cumulative metrics that can be used in these ways. See Aggregation for more information.

Naming rules

The following table lists the formats of metric type names:

Format for name of metric type	Description
[SERVICE].googleapis.com/[PATH]	Metrics for Google Cloud Platform
aws.googleapis.com/[SERVICE]/[PATH]	Metrics for Amazon Web Services
agent.googleapis.com/[SERVICE]/[PATH]	Metrics from the Monitoring agent
logging.googleapis.com/[PATH]	Logs-based metrics from Stackdriver Logging
custom.googleapis.com/[PATH]	Custom metrics
external.googleapis.com/prometheus/[PATH]	Prometheus metrics

In the preceding table, [SERVICE] identifies a product, such as compute for Compute Engine. [PATH] identifies a metric type within the product, such as instance/cpu/utilization.

Monitoring defines the metric types in the first three rows of the table. You can access those metric types in all Cloud Platform projects.

You define the metric types in the last three rows of the preceding table. You can access those metrics in the projects where you define the metrics.

You must adhere to the following spelling rules for metric type names:

• You can use upper and lower-case letters, digits, and underscores (_) in the names.
• You can use periods (.) in the domain part of the names.
• 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 name is 200 characters.

You must adhere to the following spelling rules for metric label names:

• You can use upper and lower-case letters, digits, underscores (_) in the names.
• You can start names with a letter or digit.
• The maximum length of a metric label name is 100 characters.

Time series and labels

A time series (type TimeSeries) is a sequence of time-stamped data points (type Point). In addition to the data points, each time series specifies the following:

• A metric type name.
• A source of the data in the time series (type MonitoredResource).
• A value for each of the metric type's labels.

Use the Monitoring API or the Metrics Explorer in Monitoring to inspect time series from any metric.

If you create a custom metric, then you are responsible for writing the time series data. Custom metrics can only be associated with certain monitored resource types. For more information, see Choosing a monitored resource type.

Retention of metric data

Monitoring acquires metric data and holds it in the time series of metric types for 6 weeks. At the end of that time, Monitoring deletes the expired data points.

When all the points in a time series have expired, Monitoring deletes the time series. Deleted time series do not appear in Monitoring charts or the Monitoring API.

Latency of metric data

Latency refers to how long it takes before a new metric data point is available in Monitoring. The time varies according to the monitored resource and other factors. Here are some current examples:

• Monitoring collects CPU utilization metrics from Compute Engine VM instances every minute. You can access the data 3–4 minutes after the time recorded with the data.

  There is an additional delay before you can access the first data point in a new time series.

• When you use the Monitoring API to write a new data point to an existing time series, you can access the data in a few seconds.

  When you write the first data point to a new time series, you might have to wait a couple of minutes before you can access the data.