This page is an in-depth continuation of the discussion and examplespresented inMetrics, time series, and resources andComponents of the metric model. To get themost from this page, read those pages first.

• This page maps the general metric model to the Cloud Monitoring API, so itis useful for anyone using the Monitoring API directly. Users whoseprimary interaction is with the Google Cloud console probably don't need thislevel of detail.

• It is also useful to anyone using a third-party integration likeOpenTelemetry. As data from an external sourcereaches Cloud Monitoring through an integration, it is mapped to theCloud Monitoring metric model and treated like any other metric data.

For more on collecting your own metrics, seeUser-defined metrics overview.

Review of the metric model

A prerequisite for understanding the structure of time series is familiaritywith the metric model used by Cloud Monitoring. This model is described inMetrics, time series, and resources. This sectionprovides a brief review.

In general terms, monitoring data is recorded intime series. Each individualtime series includes three pieces of information relevant to this discussion:

• A set of time-stamped data points.
• A reference to the metric type that tells you how to interpret the data points.
• A reference to the monitored resource from which the data originated.

Time series:Points: [(value1, time1), (value2, time2), ...]Metric type information: integer? incremental?Monitored resource: project? location? method?

Each time series holds the measurements from a single physical or logical source.If your environment has hundreds of resources, each contributes at least onetime series. In fact, if your metric type and monitored-resource type havelabels, you get one time series per combination of label values; seeCardinality for more information.

A sample time series

A time series is represented as an instance of aTimeSeries object.The following is a complete instance of a single time series:

    {"metric": {        "labels": {          "log": "kubelet",          "severity": "DEFAULT"        },        "type": "logging.googleapis.com/log_entry_count"      },"resource": {        "type": "gce_instance",        "labels": {          "instance_id": "5106847938295940291",          "zone": "us-central1-a",          "project_id": "a-gcp-project"        }      },      "metricKind": "DELTA",      "valueType": "INT64","points": [        {          "interval": {            "startTime": "2019-12-20T20:25:38Z",            "endTime": "2019-12-20T20:26:38Z"          },          "value": {            "int64Value": "20"          }        }      ]    }

Most time series include a lot more data points; this one coversa one-minute interval. All time series have the same structure, with thefollowing fields:

• Themetric field records

  • The metric-label values for this particular time series, representing onecombination of label values.
  • The metric type with which the data is associated. The metric type specifiesthe available labels and describes what is represented by thedata points.

  The information in this field is described in more detail inMetrics.

• Theresource field records:

  • The resource-label values for this particular time series, representing onecombination of label values.
  • The specific monitored resource from which the data was collected.

  The information in this field is described in more detail inMonitored-resource objects.

• ThemetricKind andvalueType fields tell you how to interpret the values.For more information, seeMetric kinds and types.

• Thepoints field is an array of timestamped values. The metric type tellsyou what the values represent. The sample time series has an array with asingle data point; in most time series, the array has many more values.

For a live example that retrieves time series data, seeTime series: data froma monitored resource.

This rest of this page looks at the information in themetric andresource fieldsin more detail.

Monitored resources

Cloud Monitoring collects data from monitored resources and records itin time series. Each time series created includes a description of themonitored resource from which the data was collected.

Monitored-resource objects

A monitored resource is represented by an instance of aMonitoredResource object. The monitored resource describesthe source of the values in a time series.TheMonitoredResource object is embedded into the time series andidentifies a specific instance of a monitored-resource type known toMonitoring: it points to a physical or logical entity.

For example, here is a monitored-resource object describing a particularCompute Engine instance, extracted from the example time series:

"resource": {        "type": "gce_instance",        "labels": {          "instance_id": "5106847938295940291",          "zone": "us-central1-a",          "project_id": "a-gcp-project"        }      }

This instance of a monitored resource is of the typegce_instance, it hasa specificinstance_id value (5106847938295940291) in the projecta-gcp-project.The instance is located in the US. Another time series might originate from a differentinstance of this monitored resource. Each combination of label values identifies aunique resource from which data is collected.

Different sets of labels make sense for different resources. The set of labelsfor a resource is determined by the monitored-resource descriptor for that type.

Monitored-resource descriptors

The information about a monitored-resource type is held in a data structurecalled amonitored-resource descriptor. For a definition of thisdata structure, seeMonitoredResourceDescriptor.

A monitored-resource descriptor is like a schema or specification for a recordstructure. It doesn't contain the data about a particular instance of themonitored resource; it tells you how to describe a monitored resource of aspecific type. For example, here is the monitored-resource descriptor for thegce_instance resource:

{"type": "gce_instance",  "displayName": "VM Instance",  "description": "A virtual machine instance hosted in Compute Engine.","name": "projects/[PROJECT_ID]/monitoredResourceDescriptors/gce_instance""labels": [    {      "key": "project_id",      "description": "The identifier of the GCP project associated with this resource, such as \"my-project\"."    },    {      "key": "instance_id",      "description": "The numeric VM instance identifier assigned by Compute Engine."    },    {      "key": "zone",      "description": "The Compute Engine zone in which the VM is running."    }  ],}

Compare this monitored-resource descriptor to the specific instance of agce_instance resource shown inMonitored-resourceobjects.This descriptor doesn't describe a particular monitored resource; instead,the descriptor specifies the labels, and each combination of label valuesidentifies a particular monitored resource.

You can retrieve the monitored-resource descriptors in your Google Cloud projectby using the Cloud Monitoring API. See, for example, the reference pages for themonitoredResourceDescriptors.list andmonitoredResourceDescriptors.get methods.

Live example: If you have a Google Cloud project, you can retrieve thisdescriptor by using the APIs Explorer widget as follows:

1. Open themonitoredResourceDescriptors.listreference page.

2. In the pane labeledTry this method, enter the following:

   • name:projects/PROJECT_ID/monitoredResourceDescriptors/gce_instance

     ReplacePROJECT_ID with the ID of your Google Cloud project.

3. ClickExecute.

The request returns the preceding descriptor.

For examples using the Monitoring API methods, seeList metric and resource types.

Metrics

Each time series created by Cloud Monitoring records a set of data pointsas well as information about the organization and meaning of those data points.

Metric objects

Each time series includes a reference to the description of the databeing recorded in a metric object.

The metric object contained in a time series specifies the type of measurementsand metric-specific information about those measurements.For a definition of the metricobject data structure, seeMetric.For example, here is the metric objectextracted from the time series inA sample time series:

    {"metric": {        "labels": {          "log": "kubelet",          "severity": "DEFAULT"        },        "type": "logging.googleapis.com/log_entry_count"      }

This object tells you that the time series containslogging.googleapis.com/log_entry_count measurements. The labelvalues tell you that this specific time series counts only log entriesof severityDEFAULT in the log file calledkubelet.

There is one time series for each combination of label values, soINFO entries to the same log file appear in a different time series.

The set of labels collected in a metric object isspecified in the descriptor for that metric type.

Metric descriptors

The information about a metric type is held in a data structure calledametric descriptor. For a definition of thisdata structure, seeMetricDescriptor.

A metric descriptor is a schema or specification for a record structure. Itdoesn't contain the data about a particular metric; rather, it tells you how to interpretthe data associated with a specific metric type.

Here is an example metric descriptor:

{  "type": "logging.googleapis.com/log_entry_count",  "name": "projects/a-gcp-project/metricDescriptors/logging.googleapis.com/log_entry_count",  "labels": [    {      "key": "log",      "description": "Name of the log."    },    {      "key": "severity",      "description": "Severity of the log entry."    }  ],  "metricKind": "DELTA",  "valueType": "INT64",  "unit": "1",  "description": "Number of log entries that contributed to user-defined metrics.",  "displayName": "Log entries",  "metadata": {    "launchStage": "GA",    "samplePeriod": "60s"  },  "launchStage": "GA"}

Compare this metric descriptor to the metric object shown inMetric objects. The descriptor tells you what thelabel values mean, as well as how to interpret the values of the data points.

You can retrieve metric descriptors by using the Cloud Monitoring API. See, forexample, the reference pages for themetricDescriptors.list andmetricDescriptors.get methods.

Live example: If you have a Google Cloud project, you can retrieve thisdescriptor by using the APIs Explorer widget as follows:

1. Open themetricDescriptors.list reference page.

2. In the pane labeledTry this method, enter the following:

   • name:projects/PROJECT_ID/metricDescriptors/logging.googleapis.com/log_entry_count ReplacePROJECT_ID with the ID of your Google Cloud project.

3. ClickExecute.

The request returns the preceding descriptor.

For examples using the Monitoring API methods, seeList metric and resource types.

Most of the fields in the metric descriptor are self-explanatory. Thetwo likely to need further explanation are the metric kind and value type,which are described further inMetric kinds and types.