Metrics, Time Series, and Resources

This page introduces the Google Cloud Platform concepts of metric, time series, and monitored resource.

Overview

A metric is a measurement of some characteristic of your cloud application. For example, Stackdriver 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, Stackdriver 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 Stackdriver 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 metric.

  • Time series. Cloud Platform 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. Cloud Platform 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.

Next steps

Now that you have an overview, the following sections include more details about monitored resources, metrics, and time series.

Monitored Resources

A monitored resource (type MonitoredResource) is a structured name that identifies an entity known to Cloud Platform. 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 Stackdriver 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 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 for charting or alerting in Stackdriver Monitoring.

Naming rules

The following table lists the formats of metric type names:

Metric type name format 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.

Stackdriver 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 100 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 set of values for the metric type's labels.

Google Cloud Platform services write the time series data for their monitored resources and for logs-based metrics. If you create custom metrics, you are responsible for writing the time series data for your metrics.

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

Retention of metric data

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

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

Latency of metric data

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

  • Cloud Platform 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 Stackdriver 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.

Send feedback about...

Stackdriver Monitoring