This page explains how to read metric data, also called time-series data, using
the timeSeries.list
method in the
Monitoring API.
This page does not discuss Monitoring Query Language (MQL) and the
timeSeries.query
method. For that
information, see Using MQL from the
Monitoring API.
There are several ways to use the timeSeries.list
method:
To run the
list
method without writing any code, the examples in the PROTOCOL tabs on this page use the forms-based API Explorer. (See API Explorer for more information on this tool.)To learn how to use the
list
method from selected programming languages, see the runnable code samples on this page. There is no Cloud SDK support for using thegcloud
command-line tool to read metric data.-
To view the metrics for a monitored resource using Metrics Explorer, do the following:
- In the Google Cloud Console, go to Monitoring or use the following button:
Go to Monitoring - In the Monitoring navigation pane, click
Metrics Explorer.
- Enter the monitored resource name in the Find resource type and metric text box.
- In the Google Cloud Console, go to Monitoring or use the following button:
For an introduction to metrics and time series, see Metrics, time series, and resources.
Overview
Each call to the timeSeries.list
method can return
any number of time series from a single metric type. For example, if you are
using Compute Engine, then the compute.googleapis.com/instance/cpu/usage_time
metric type has a separate time series for each of your VM instances.
You specify which time series data you want by supplying the following:
- A filter expression that specifies the metric type. Optionally, the filter selects a subset of the metric's time series by specifying the resources producing the time series or specifying values for certain labels in the time series.
- A time interval that limits how much data is returned.
- Optionally, a specification of how to combine multiple time series to produce an aggregate summary of the data. For more information, see Aggregating data for some examples.
Time series filters
You specify which time series to retrieve by passing a
time series filter to the list
method. Following are the commonly-provided filter components:
The filter must specify a single metric type. For example:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
To retrieve custom metrics, change the metric.type prefix in the filter to
custom.googleapis.com
or another prefix if used;external.googleapis.com
is frequently used.The filter can specify values for the metric's dimension labels. The metric type determines which labels are present. For example:
(metric.label.instance_name = "your-instance-id" OR metric.label.instance_name = "your-other-instance-id")
Note that
label
is correct, although the actual metric object useslabels
as its key.The filter can limit the time series to those that contain a specific monitored resource type:
resource.type = "gae_app"
The filter components can be combined into a single time series filter, such as the following:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
AND (metric.label.instance_name = "your-instance-id" OR
metric.label.instance_name = "your-other-instance-id")
If you do not specify values for all the metric labels, then the list
method
returns a time series for each combination of values in the unspecified
label(s). The method returns only time series that have data.
Time intervals
You must specify interval.startTime and interval.endTime when calling
the timeSeries.list
method. The resulting time period includes the end time
but not the start time, unless they are both the same time. This can be
confusing. For example, consider these examples of (start, end]
intervals:
(T, T+1]
- This interval does not contain T.
(T-1, T]
- This interval does contain T.
(T, T]
- As a special and unusual case, this interval includes only the time T. If you omit the start time, this is the interval you get.
Values in time intervals
Start and end times must be specified as strings in RFC 3339 format. For example:
2018-05-11T12:34:56+04:00 2018-05-11T12:34:56.992Z
The date -Iseconds
command on Linux is useful for generating timestamps.
Ranges in time intervals
A time interval is specified by a start and end time, but the start time
is not required by the API. If a start time is not specified, it defaults to
the end time. This makes semantic sense only for GAUGE
metrics, which
measure points in time.
If your metric is CUMULATIVE
or DELTA
, then it measures an
accumulation or change over time. For “over time” metrics,
the start and end times of the interval must both be supplied, and
the start time must be less than the end time.
See Kinds of metrics for more information.
Basic list operations
The timeSeries.list
method can be used to return simple, raw data, or it
can be used to return highly processed data. This section illustrates some
basic uses.
Example: Listing available time series
This example shows how to list only the names and descriptions of the time series that match a filter, rather than returning all the available data:
Protocol
Here are the sample parameters to
timeSeries.list
:
- name:
projects/[PROJECT_ID]
- filter:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- fields:
timeSeries.metric
Before clicking the Execute button, change [PROJECT_ID]
to your ID of
your project.
The sample output shows time series for two different VM instances:
{
"timeSeries": [
{
"metric": {
"labels": {
"instance_name": "your-first-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
},
{
"metric": {
"labels": {
"instance_name": "your-second-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
See Troubleshooting API calls if you have difficulty.
Example: Getting time series data
This example returns all the information available to the timeSeries.list
request, including the metric data, from Compute Engine instances for the
last 20 minutes.
Protocol
The protocol example further limits the output, to make the returned data more manageable in the response box. This example uses different field values:
- The filter value now limits the time series to a single VM instance.
- The fields value now specifies only the time and value of the measurements.
These limit the amount of time series data returned in the result.
Here are the sample parameters to
timeSeries.list
:
- name:
projects/[PROJECT_ID]
- filter:
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "[YOUR_INSTANCE_NAME]"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- fields:
timeSeries.points.interval.endTime,timeSeries.points.value
Before clicking the Execute button, change [PROJECT_ID]
and
[YOUR_INSTANCE_NAME
] to values in your project, and set the end
time to something recent and the start time to 20 minutes earlier.
The request returns a result like the following:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2018-05-T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2018-05-11T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2018-05-11T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
The returned data includes 20 data points in each time series over the 20-minute period, because Compute Engine metrics are collected every minute. For more information, see Retention and latency of metric data. The API returns the data points in each time series in reverse time order; there is no override for this point ordering.
See Troubleshooting API calls if you have difficulty.
Aggregating data
The timeSeries.list
method can perform statistical aggregations and reductions on the returned time
series data. The following sections demonstrate two examples;
see the method's documentation for more options.
Example: Aligning time series
This example reduces the 20 individual utilization measurements in each time series to just two measurements: the mean utilization for the two 10-minute periods within the 20-minute interval. The data from each time series is first aligned into 10-minute (600-second) periods, and then the values in each 10-minute period are averaged.
This example turns the twenty measurements per time series into two per time series. This operation has two advantages: it smooths out the data, and it aligns the data from all of the time series on exact 10-minute boundaries. The data can then be processed further.
Protocol
Here are the sample parameters to
timeSeries.list
:
- name:
projects/[PROJECT_ID]
- aggregation.alignmentPeriod:
600s
- aggregation.perSeriesAligner:
ALIGN_MEAN
- filter:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- fields:
timeSeries.metric,timeSeries.points
The filter for a single instance shown in the previous example is removed: this query returns much less data, so there is less need to restrict it to one VM instance.
Before clicking the Execute button, change [PROJECT_ID]
to the ID
for your project, and adjust the end time to something recent and the start time to 20 minutes earlier.
The following sample result has a time series for each of three VM instances. Each time series has two data points, the mean utilization for the 10-minute alignment periods:
{
"timeSeries": [
{
"metric": {
"labels": {"instance_name": "your-first-instance"},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
See Troubleshooting API calls if you have difficulty.
Example: Reducing across time series
This example extends the previous example by combining the aligned time series from the three VM instances into a single time series that measures the average utilization of all instances.
Protocol
Following are the sample parameters to
timeSeries.list
,
aggregation.crossSeriesReducer:
- name:
projects/[PROJECT_ID]
- aggregation.alignmentPeriod:
600s
- aggregation.crossSeriesReducer:
REDUCE_MEAN
- aggregation.perSeriesAligner:
ALIGN_MEAN
- filter:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- fields:
timeSeries.metric,timeSeries.points
Before clicking the Execute button, change [PROJECT_ID]
to the ID for
your project, and adjust the end time to something recent and the start time to
20 minutes earlier.
The following sample result has only one time series and two data points. Each point is the average of the utilization among the three VM instances during the time period:
{
"timeSeries": [
{
"metric": {
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
See Troubleshooting API calls if you have difficulty.