Components of the metric model

Stay organized with collections Save and categorize content based on your preferences.

Cloud Monitoring's model for monitoring data consists of three primary concepts:

  • Monitored-resource types
  • Metric types
  • Time series

The Cloud Monitoring metric model describes these concepts in general terms. If these concepts are new to you, read that page first.

This page describes metric types, monitored resources, and time series, along with some related concepts, in more detail. These concepts underlie all Monitoring metrics.

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

For more detail on these concepts and how they map to the Cloud Monitoring API, see Structure of time series, particularly if you plan to use the Monitoring API or custom metrics.

A word about labels

Monitored-resource types and metric types both support labels, which allow data to be classified during analysis. For example:

  • A monitored-resource type for a virtual machine might include labels for the location of the machine and the project ID associated with the machine. When information about the monitored resource is recorded, the information includes the values for the labels.

    A monitored resource might also have system- or user-provided metadata labels, in addition to the labels defined for the monitored-resource type.

  • A metric type that counts API requests might have labels to record the name of the method invoked and the status of the request.

The use of labels is discussed in more detail in Labels.

Monitored-resource types

A monitored resource is a resource from which metric data is captured. At last count, Cloud Monitoring supports approximately 100 types of monitored resources.

Types of monitored resources include generic nodes and tasks, tables in Cloud Bigtable, architectural components in Google Kubernetes Engine, various AWS resources, and many more.

Each type of monitored resource is formally described in a data structure called a monitored-resource descriptor. For more information, see Monitored resource descriptors.

Each of the supported monitored-resource types has an entry in the Monitored resource list. The entries in the list are created from the monitored-resource descriptors. This section describes the information captured in a monitored-resource descriptor and shows how it is presented in the list.

A sample monitored-resource type

Here is the entry in the list for a Cloud Storage bucket:

Listing for the Cloud Storage bucket.

All entries in the list include the following information:

  • Type: The header in the entry lists the monitored-resource type; gcs_bucket in the example.
  • Display name: A short description of the monitored resource.
  • Description: A longer description of the monitored resource.
  • Labels: A set of dimensions for classifying data. For more information, see Labels.

Metric types

A metric type describes measurements that can be collected from a monitored resource. A metric type includes a description of what is being measured and how the measurements are interpreted. At last count, Cloud Monitoring supports approximately 1,500 types of metrics, and it provides you the ability to define new types.

Metric types include counts of API calls, disk-usage statistics, storage consumption, and many more.

Each metric type is formally described in a data structure called a metric descriptor. For more information, see Metric descriptors.

Each of the built-in metric types has an entry in the Metrics list. The entries in these tables are created from the metric descriptors. This section describes the information captured in a metric type and shows how it is presented in reference material.

A sample metric type

The following image shows an entry of a Cloud Storage metric type:

An excerpt of the metric list for Cloud Storage.

The metric types are displayed in a table, and the table header explains the layout of the information. This section uses one entry as an example, but all the tables use the same format.

The sample Cloud Storage table entry gives you the following information about one metric type:

  • Metric type: An identifier for the metric type, in the example.

    The prefix acts as a namespace for Cloud Storage. All metric types associated with a particular monitored-resource type use the same namespace.

    Namespaces are omitted from entries in the tables.

    All the metric types associated with Cloud Storage are listed in the table for Cloud Storage metrics.

  • Launch stage: A colored block that indicates the launch stage of the metric type with a value like Alpha, Beta, and GA.

  • Display name: A brief string describing the metric type, “Request count” in the example.

  • Kind, Type, Unit: This line provides information for interpreting the data values: the example shows a delta metric recorded as a 64-bit integer with no unit (that's the 1 value).

    • Kind: This example is a delta metric, which records a change over a period of time. That is, each data point records the number of API calls since the previous data point was written. For more information on kinds, see Value types and metric kinds.

    • Type: This example records its values as 64-bit integers. For more information on types, see Value types and metric kinds.

    • Unit: This metric doesn't need an explicit unit because it represents a count; the digit 1 is used to indicate that no unit is needed.

  • Monitored resources: The monitored resources for which this metric type is available. The values here are the same as those described in Monitored-resource types.

  • Description: More detailed information about what is recorded and how. Set in italics to distinguish it from the labels.

  • Labels: A set of dimensions for classifying data. For more information, see Labels.

When you access monitoring data through the Cloud Monitoring API, you include a Google Cloud project in the API call. You can retrieve only the data that is visible to that Google Cloud project. For example, if you request your project's data for the metric type, then you see API counts only for Cloud Storage buckets in your project. If your project isn't using any Cloud Storage buckets, then no metric data is returned.

Built-in metric types

Built-in metric types are defined by Google Cloud services, including Cloud Monitoring. These metric types describe standard measurements for a wide array of common infrastructure and are available for anyone to use.

The Metrics list shows the entire set of built-in metrics types. Metrics listed in the External metrics list page are a special subset of built-in metrics that are defined by Cloud Monitoring in partnership with open-source projects or third-party providers. Typically, these metrics have a prefix of

Custom metrics

When you build your application, you might have certain properties you want to measure, things for which there are no built-in metrics. With Cloud Monitoring, you can define your own metric types. These metric types are called custom metrics. If a metric has a prefix of or, then it is a custom metric. The latter metrics usually come from the Stackdriver Prometheus sidecar. See Using Prometheus for more information.

For example, if you want to track the number of widgets sold by your stores, you need to use a custom metric. For more information, see Using custom metrics.


The definitions of both metric and monitored-resource types include labels. Labels are classifiers for the data being collected; they help to categorize the data for deeper analysis. For example:

  • The Cloud Storage metric type has two labels, response_code and method.
  • The Cloud Storage monitored-resource type gcs_bucket has three labels, project_id, bucket_name, and location. The labels identify specific instances of the resource type.

Therefore, all data collected for API requests from a Cloud Storage bucket is classified by the method that was called, the response code for the call, the name, location, and project of the bucket involved. The set of labels varies with the metric or monitored-resource type; the available labels are documented in the Metrics list and Monitored resource list pages.

By tracking the response code, method name, and location when counting API calls, you can then fetch the number of calls to a particular API method, or the number of failing calls to any method, or the number of failing calls to a specific method in a specific location.

The number of labels and the number of values each can assume is referred to as cardinality. The cardinality is the number of possible time series that might be collected for a pair of metric and monitored-resource types: there is one time series for each combination of values of their labels. This is discussed further in Cardinality: time series and labels.

Resource metadata labels

In addition to the labels defined on the metric and monitored-resource types, Monitoring internally collects additional information on monitored resources and stores this information in system metadata labels. These system metadata labels are available to users as read-only values. Some resources also allow users to create their own resource metadata labels when configuring resources like VM instances in the Google Cloud console.

The system and user metadata labels are collectively called resource metadata labels. You can use these labels like the labels defined on the metric and monitored-resource types in time-series filters. For more information on filtering, see Monitoring filters.

Time series: data from a monitored resource

This section discusses what monitoring data is and how it's organized in time series. This is where the conceptual components of the metric model become concrete artifacts.

Cloud Monitoring store regular measurements over time for pairs of metric and monitored-resource types. 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, and one combination of values for the metric's labels.

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

  • The monitored resource that is the source of the time series data, and one combination of values for the resource's labels.

A time series is created for each combination of metric and resource labels that generates data.

Stylized example: The metric type described above could have many time series for your project's Cloud Storage buckets. The following illustration shows some possible time series.

In the illustration, the value bucket: xxxx represents the value of the bucket_name label in the monitored-resource type, and response_code and method are labels in the metric type. There is one time series for each combination of values in the resource and metric labels; the illustrations shows some of them:

Images showing multiple time series in a metric

Cloud Monitoring does not record “empty” time series. In the Cloud Storage buckets example, if you are not using a particular bucket or never call a particular API method, then no data is collected for that label, and no time series mentions it. This means that, if your project has no data at all for a particular metric, you never see the metric type.

The metric types don't 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 pair with more than one monitored resource.

Live example: If you have a Google Cloud project, you can try the APIs Explorer widget, located on the reference page for the timeSeries.list method in the Monitoring API. The TRY IT button below supplies the following default parameters to the timeSeries.list method:

  • name: projects/[PROJECT_ID]
  • filter: metric.type="" resource.type="gce_instance"
  • interval.start_time: 2019-11-11T00:00:00Z
  • interval.end_time: 2019-11-11T00:20:00Z
  • fields: timeSeries.metric

When you try to run this example, you must change [PROJECT_ID] in the name field to your project ID.

This example assumes you have a Compute Engine instance running the Cloud Logging agent. The monitored-resource type is gce_instance, and the metric type is You can change these values if they don't apply to you.

When retrieving time-series data, you must specify start and end times. This example uses a period on 11 November 2019. However, time-series data is stored for 6 weeks, so you will probably have to adjust the date as well before running the request.

To run the request, click the button below, adjust the parameters as needed, and click the Execute button at the bottom of the widget panel.

Try It!

If the request succeeds, it will return the time-series data that matches the request. It will look like the following snippet:

  "timeSeries": [
      "metric": {
        "labels": {
          "severity": "INFO",
          "log": ""
        "type": ""
      "resource": {
        "type": "gce_instance",
        "labels": {
          "instance_id": "0",
          "zone": "us-central1",
          "project_id": "your-project-id"
      "metricKind": "DELTA",
      "valueType": "INT64",
      "points": [
        "interval": {
            "startTime": "2019-10-29T13:53:00Z",
            "endTime": "2019-10-29T13:54:00Z"
          "value": {
            "int64Value": "0"

For more information on using this widget, including troubleshooting, see APIs Explorer.

Cardinality: time series and labels

Each time series is associated with a specific pair of metric and monitored-resource types, but each pair can have many time series. The possible number of time series is determined by the cardinality of the pair: the number of labels and the number of values each label can take on.

For example, suppose you have a trivial metric type that specifies one label, color, and a monitored-resource type with another label, zone. You get a time series for each combination of zone and color values.

The number of values a label can assume is important:

  • If there are only two possible zones, “east” and “west”, the zone label can have up to two distinct values.
  • If there are only three possible colors, “red,” “green,” and “blue,” the color label can have up to three distinct values.

Cardinality depends on labels and their values.

The cardinality of this metric is 6 (3×2), though the metric might produce fewer time series. If, for example, you never get any data from the “west” zone, then you will never have more than three time series.

Metric cardinality is a critical factor in performance when you are requesting metrics for a chart or other uses. Higher cardinality can lead to slower query response times.

Cardinality is also a concern when designing custom metrics, where you determine the set of labels and their possible values. You are limited to 30 labels in a metric type, but you also need to ensure than the set of possible values for any label is constrained. A small set of discrete values (like “red,” “green,” and “blue,”) is the preferred approach. Granular values, such as timestamps, should not be used. There are other limits on custom metrics, as well; see Custom metrics for more information.