Metrics, Time Series, and Resources

Metrics help you understand how your applications and system services are performing. Stackdriver defines over a thousand metric types that help you monitor GCP, AWS, and third-party software. You can also create your own custom metrics.


You should understand the information on this page if you want to do any of the following:

The following sections introduce metric types and time series, which underlie all GCP metrics. For more detailed information about these concepts, see Structure of Metric Types.

Metric types

To browse a list of all the built-in metric types, see the Metrics List. Here is a listing of one of the metric types from that page:

Cloud Storage metrics sample

This listing gives you the following information about the metric type:

  • The metric type's name is

  • The metric records the "count of API calls" in Cloud Storage. This is a delta metric, which means each metric data point records the number of API calls since the previous data point was written.

    You can only access metric data belonging to your current GCP project (or Workspace). If you were to fetch the data from this metric type, you would see API counts for only your project's Cloud Storage buckets.

  • The metric data is grouped by (or labeled with) a response code and method name. That means, for example, you can fetch the number of calls to a single API method, or the number of failing calls to any API method.

This information about a metric type is held in a data structure called a MetricDescriptor, which you can access through the Monitoring API.

Time series

This section discusses what "metric data" is and how it's organized.

For each metric type, Stackdriver and GCP store regular measurements over time. The measurements are collected into time series, and each time series contains the following items:

  • The name of the metric type to which the time series belongs.

  • A series of (timestamp, value) pairs. The value is the measurement and timestamp is the time of the measurement.

  • The monitored resource that is the source of the time series data.

  • A value for each of the metric type's labels.

All the points in a time series have the same values for the name of the metric type, the name of the monitored resource, and the values for each of the labels.

Example: The metric type described above could have many time series for your project's Cloud Storage buckets. In the following samples, the value bucket xxxx represents the monitored resource:

[bucket 1234, response:OK,   method: read]  {(Wed 2:00pm, 3), (Wed 2:05pm, 2), (Wed 2:10pm, 8), ...}
[bucket 1234, response:OK,   method: write] {(Wed 2:01pm, 1), (Wed 2:04pm, 2), (Wed 2:09pm, 7), ...}
[bucket 1234, response:FAIL, method: write] {(Wed 2:01pm, 1), (Wed 2:04pm, 0), (Wed 2:09pm, 0), ...}
[bucket 9876, response:OK,   method: read]  {(Wed 1:59pm, 2), (Wed 2:05pm, 4), (Wed 2:10pm, 3), ...}

GCP does not record "empty" time series. For example, if you are not using a particular bucket or a particular API method, then there will be no time series mentioning that bucket or that method.

The metric type descriptions do not indicate what types of monitored resources are found in the metrics' time series. For Cloud Storage, there is only one monitored resource type—gcs_bucket. Some metric types use more than one type of resource.

You can see the complete list of available monitored resource types in Monitored Resource Types.

Aggregating time series

You can use aggregation to combine data from several time series into one time series.

Example: Using the previous metric type and time series, suppose you want a count of how many successful calls there are to the write API method in a 24-hour period. That result depends on data in many time series, and the Monitoring API can aggregate time series to get your result. By supplying parameters to the method, you can do the following:

  • Specify the metric type and the label values method:write and response:OK. This results in fewer input time series, since you don't include time series for failing calls or for calls to other methods.

  • Limit the time series data to the desired time period by specifying a start time and an end time. This makes each input time series shorter by discarding metric data before and after the time period.

  • Sum all the data points in each individual time series. Each time series now has only one data point—the number of successful write calls to a single bucket for one day.

  • Sum all the time series together. This results in a new time series with a single data point: the result you wanted.