Monitoring Query Language reference

This is a reference manual for the Cloud Monitoring Monitoring Query Language. It covers the following topics:

• The data model underlying the time series database that the Monitoring Query Language accesses.

• The structure and semantics of queries.

• A description of each of the operations and functions that a query is built from.

Data Model

Cloud Monitoring uses a time series database that contains all the measurements it has ingested about each thing it is monitoring (known as a monitored resource). This describes the logical structure of that database.

The fundamental element is a time series whose data consists of observations of the monitored resource being monitored.

Time series in the database are logically organized into relational tables, each containing time series with a common meaning and structure. The tables are referenced by queries that return data, generate graphs, and compute alerts.

The database also includes metadata, which are slowly changing values associated with a monitored resource and which are set by user configuration or by the service that implements the monitored-resource type.

Time series

A time series is a named sequence of points, each being a measured value and the time to which the value applies. A time series consists of three parts: a type, which specifies the structure of the time series, an identifier, which uniquely names the time series, and a history, which contains the time series data. Each of these three parts are explained in this section.

A time series type specifies the structure of the time series identifier and the time series history. It consists of two parts:

• A monitored-resource type (listed here) that names a particular kind of monitored resource that is monitored, such as a Compute Engine instance (gce_instance) or a cloud SQL database (cloudsql_database). It has a set of label descriptors that uniquely identify an instance of that type of monitored resource.

• A metric type (listed here) that describes a particular kind of measurement that can be taken on a monitored resource, for example bytes read from disk by a Compute Engine instance is measured by the metric named compute.googleapis.com/instance/disk/read_bytes_count, and the data utilization of a cloud SQL database is measured by the metric named cloudsql.googleapis.com/database/disk/bytes_used. The metric type specifies the type of measurement's value, the units of the measurement, and the kind of time series. It may specify label descriptors that distinguish time series measuring different aspects of the same thing. For example command indicating what command is counted in the appengine.googleapis.com/memcache/operation_count metric.

Note that a monitored resource type and a metric type are described by a MonitoredResourceDescriptor and a MetricDescriptor, respectively. These describe the types. They each contain a field named type which contains the name of that monitored resource or metric type.

A time series identifier is the name of the time series, uniquely identifying it among all time series with the same type. It consists of a set of values, one for each of the label descriptors specified in the monitored resource and metric types that make up the time series type.

• The labels from the monitored-resource type uniquely identify the particular instance of the kind of monitored resource from which the measurements in the time series were taken. For example, the gce_instance monitored resource has labels project_id, instance_id, and zone which uniquely identify a particular Google Compute Engine virtual machine.

• Each label from the metric type identifies which specific kind of measurement for the given metric is represented in the time series. For example status indicating the status of the commands counted in the appengine.googleapis.com/memcache/operation_count metric might have value 'HIT' for one time series that counts hits and 'MISS' for another time series that counts misses.

A time series history is a time-ordered sequence of points, each representing a simultaneous measurement of one, or, potentially, several values (for example, CPU load or temperature and humidity) at some time or over some time range. A point has two elements:

• A point's extent in time consists of an end time, which is always present, and a start time which may or may not be present. If the start time is not present, the point's extent is a single point in time given by the end time. If the start time is given, it must be before the end time and the point's extent is the time interval starting at the start time and ending at the end time.

  No two points in a time series can have the same extent. In addition, the extents of the points in a time series are constrained by the time series kind given by the metric type as described below.

• A point's value represents a simultaneous measurement of one, or, potentially, several values (for example, CPU load or temperature and humidity) that applies to the time given by the point's extent. The metric type describes each measurement value, giving it a name and a value type for each. If there are multiple measurement values, they are in a particular order and can be reference by their index in that order.

  A typical time series stored in the time series database has a single value in each point. The name of the metric in the time series type is a URI and the name of the single value is the part of the metric name after the last /. For example, the metric appengine.googleapis.com/memcache/operation_count has a value column named operation_count.

  A time series that is the output of a query may have multiple points whose type, name, and order are given by the query.

  The metric type may also specify units of measurement for the time series value if it is of type Int, Double, or Distribution. The units are given using a subset of the Unified Code for Units of Measure (UCUM). For example, ms for milliseconds or By for bytes. See Units of Measure for the details.

Each value in a point has a particular value type, which is specified by the metric type in the time series type. Also each label in the time series identifier has a value type, given by the label descriptor in the time series type's monitored resource or metric type. The value types are as follows.

• Int: A 64-bit signed integer.