This document explains how to read metric data, also called time-series data,
by using the
timeSeries.list
method in the
Monitoring API.
There are several ways to call the
timeSeries.list
method:
- You can use the
Protocol
tabs on this page to use the forms-based
APIs Explorer
.
- You can use a language-specific client library.
- You can use the Metrics Explorer.
Another way to read your metric data is to send a command to the
timeSeries.query
method,
which requires Monitoring Query Language (MQL). This document doesn't describe
MQL or the
timeSeries.query
method. For information about those
topics, see
Retrieving data with
timeSeries.query
.
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.
For an introduction to metrics and time series,
see
Metrics, time series, and resources
.
You specify the time-series data that you want by providing the following
information to the
timeSeries.list
method:
- 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 and
examples, see
Aggregating data
.
Time-series filters
You specify which time series to retrieve by passing a
time-series filter
to the
timeSeries.list
method.
The following lists the common filter components:
The filter must specify a single metric type. For example:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
To retrieve user-defined 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")
In the previous expression,
label
is correct even though the actual metric
object uses
labels
as its key.
The filter can select only those time series that contain a
specific monitored resource type:
resource.type = "gce_instance"
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 don't specify values for all metric labels, then the
list
method
returns a time series for each combination of values in the unspecified
labels. The method returns only time series that have data.
Time intervals
When you use the API to read data, you specify the time interval
for which you want to retrieve data by setting start and end times.
The API retrieves data from the interval
(start, end]
, that is,
from after the start time through the end time.
The start time must be no later than the end time. If you specify a start time
that is later than the end time, then the API returns an error.
If you want to retrieve only data with a specific timestamp, then set the start
time equal to the end time, or equivalently, don't set the start time.
Start and end times must be specified as strings in RFC 3339 format.
For example:
2024-03-01T12:34:56+04:00
2024-03-01T12:34:56.992Z
The
date -Iseconds
command on Linux is useful for generating timestamps.
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
how to list the available time series and how to get the values
in a specific time series.
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
Open the
timeSeries.list
reference page.
In the pane labeled
Try this method
, enter the following:
-
name
: Enter your the path to your project.
projects/
PROJECT_ID
-
filter
: Specify the metric type.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
-
interval.endTime
: Enter the end time.
-
interval.startTime
: Enter the start time and ensure that it is 20 minutes
earlier than the end time.
Click
Show standard parameters
, and in the
fields
enter the
the following:
timeSeries.metric
Click
Execute
.
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"
},
}
]
}
To view the request as a
curl
command, as an
HTTP request, or in JavaScript, click
fullscreen
Full screen
in APIs Explorer.
If you have difficulty, see
Troubleshoot the Monitoring API
.
Example: Getting time series data
This example returns the CPU utilization measurements that were recorded over
a 20-minute interval for a specific Compute Engine instance. The amount of
data returned depends on the sampling rate of the metric. Because the
CPU utilization is sampled every minute, the results of
this query is about 20 data points. When multiple data points are
returned for a time series, the API returns the data points in each
time series in reverse time order; there is no override for this point ordering.
Protocol
The protocol example further limits the output, to make the returned
data more manageable in the response box:
- The
filter
value limits the time series to a single VM instance.
- The
fields
value specifies only the time and value of the
measurements.
These settings limit the amount of time series data returned in the result.
Open the
timeSeries.list
reference page.
In the pane labeled
Try this method
, enter the following:
-
name
: Enter your the path to your project.
projects/
PROJECT_ID
filter
: Specify the metric type.
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "
INSTANCE_NAME
"
interval.endTime
: Enter the end time.
interval.startTime
: Enter the start time and ensure that it is 20 minutes
earlier than the end time.
Click
Show standard parameters
, and in the
fields
enter the
the following:
timeSeries.points.interval.endTime,timeSeries.points.value
Click
Execute
.
The request returns a result like the following:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2024-03-01T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2024-03-01T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2024-03-01T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
To view the request as a
curl
command, as an
HTTP request, or in JavaScript, click
fullscreen
Full screen
in APIs Explorer.
If you have difficulty, see
Troubleshoot the Monitoring API
.
Aggregating data
The
timeSeries.list
method can perform statistical aggregations and reductions on the returned time
series data. The following sections demonstrate two examples.
To to learn more, see
Filtering and aggregation: manipulating time series
.
Example: Aligning time series
This example reduces the 20 individual utilization measurements in each time
series to 2 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 periods, and then the values in each
10-minute period are averaged.
The alignment operation has two advantages: it smooths out the data, and
it aligns the data from all time-series data on exact 10-minute boundaries.
The aligned data can then be processed further.
Protocol
Open the
timeSeries.list
reference page.
In the pane labeled
Try this method
, enter the following:
Click
Execute
.
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.
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": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
To view the request as a
curl
command, as an
HTTP request, or in JavaScript, click
fullscreen
Full screen
in APIs Explorer.
If you have difficulty, see
Troubleshoot the Monitoring API
.
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
Open the
timeSeries.list
reference page.
In the pane labeled
Try this method
, enter the following:
Click
Execute
.
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": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
To view the request as a
curl
command, as an
HTTP request, or in JavaScript, click
fullscreen
Full screen
in APIs Explorer.
If you have difficulty, see
Troubleshoot the Monitoring API
.
What's next