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:

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:

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.

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.

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

CUMULATIVE2

BOOL

yes

no

no

INT64

yes

yes1

yes

DOUBLE

yes

yes1

yes

STRING

yes1

no

no

DISTRIBUTION

yes

yes1

yes

MONEY

no

no

no

1 This combination is not permitted in custom metrics.2 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

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 two 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:

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.