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 useslabels
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.
Time format
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
-
name: Enter your the path to your project.
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.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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
-
name: Enter your the path to your project.
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.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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:
-
name: Enter your the path to your project.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: Enter
600s
-
aggregation.perSeriesAligner: Select
ALIGN_MEAN
-
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,timeSeries.points
-
name: Enter your the path to your project.
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.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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:
-
name: Enter your the path to your project.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: Enter
600s
-
aggregation.perSeriesAligner: Select
ALIGN_MEAN
-
aggregation.crossSeriesReducer: Select
REDUCE_MEAN
-
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,timeSeries.points
-
name: Enter your the path to your project.
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.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
If you have difficulty, see Troubleshoot the Monitoring API.
What's next
- Learn about Retention and latency of metric data.
- Learn about Filtering and aggregation: manipulating time series.