This page describes how to provide Monitoring Query Language (MQL) queries to the Cloud Monitoring API.
This page doesn't cover creating the MQL queries. For a set of example queries, see Examples. MQL Refererence provides a comprehensive reference for the language.
For general information about MQL-based alerting policies, see Alerting policies with MQL.
Using MQL from the API
You can provide MQL queries at the following places in the Monitoring API:
To select and manipulate time-series data by using MQL, call the
timeSeries.query
method. For examples, see UsingtimeSeries.query
.To select and manipulate time-series data for charts, you provide the query to a
TimeSeriesQuery
specification when you call thedashboards.create
method. For an example, see Building charts.To create MQL-based conditions in alerting policies, describe the condition for the alerting policy with the
MonitoringQueryLanguageCondition
condition type when you callalertPolicies.create
. For examples, see Creating conditions for alerting policies.
Retrieving data with timeSeries.query
To retrieve time-series data from the API with a MQL query,
use the timeSeries.query
method.
The timeSeries.query
method takes a minimal structure that looks like this
in JSON:
{ "query": string }
For the value of the query
field, specify a string in MQL, as
shown in the following simple queries:
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m" }
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | for 1h" }
{ "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time | sum | next_older 10m | every 10m" }
If your query creates an unaligned output table, then you must supply a
duration by using the within
table operation when calling
the API directly. Charting tools like Metrics Explorer provide a default
query duration. The query in the following JSON snippet works in the
MQL code editor in Metrics Explorer but fails when supplied
directly to the API:
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)" }
With the addition of a within
table operation to the prior query, the prior
example can be supplied directly to the API:
{ "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h" }
To experiment with the API, you can use the APIs Explorer tool on the
timeSeries.query
reference page.
For an introduction to APIs Explorer tool, see
APIs Explorer.
Another way to try the API is to put the query into a text file
and then execute the query using curl
. The following example passes the query
in the file query.json
to the timeSeries.query
method:
curl -d @query.json -H "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/json" -X POST \ https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query
For more information about using curl
, see Invoking curl
.
If successful, the query returns a table containing the time series requested. The table is divided into two components:
The
timeSeriesDescriptor
describes the label keys, label values, and data points in the table. It doesn't contain any data; it simply describes the data.The
timeSeriesData
contains the data described in the time-series descriptor. This data is presented as an array of pairs.- The first item in the pair,
labelValues
, records a set of values for the labels listed in the time-series descriptor. - The second,
pointData
, is an embedded array of value/timestamp pairs, which represent the data collected with the specified set of label values.
- The first item in the pair,
The response, slightly reformatted, looks like this:
[{ "timeSeriesTable": { "timeSeriesDescriptor": { "labelDescriptors": [ { "key": "resource.project_id" }, { "key": "resource.zone" }, { "key": "resource.instance_id" }, { "key": "metric.instance_name" } ], "valueDescriptors": [ { "key": "value.utilization", "valueType": "DOUBLE", "metricKind": "GAUGE" } ], "pointDescriptors": [ { "key": "value.utilization", "valueType": "DOUBLE", "metricKind": "GAUGE" } ] }, "timeSeriesData": [ { "labelValues": [ { "stringValue": "632526624816" }, { "stringValue": "us-central1-a" }, { "stringValue": "5106847938297466291" }, { "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" } ], "pointData": [ { "values": [ { "doubleValue": 0.063896992710942874 } ], "timeInterval": { "startTime": "1969-12-31T23:59:59.999999Z", "endTime": "2020-03-02T20:17:00Z" } }, { ... additional value/timestamp pairs ...} ] }, { ... additional labelValue/pointData pairs ...}, ] }
Building charts
You can use the dashboards.create
method to
programmatically create dashboards and the charts they contain.
The only difference between creating MQL-based charts
and other charts is the type of TimeSeriesQuery
query you use to populate the chart's data set.
Constructing an MQL-based chart
For MQL queries, use the query as the value of the
timeSeriesQueryLanguage
string field in the chart's DataSet
array.
The following is a simple dashboard definition that includes MQL:
{ "displayName": "Dashboard for MQL chart (API)", "gridLayout": { "widgets": [ { "title": "Min/Max Compute Engine CPU utilization", "xyChart": { "dataSets": [ { "timeSeriesQuery": { "timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union" }, "plotType": "LINE", } ], "timeshiftDuration": "0s", "yAxis": { "label": "y1Axis", "scale": "LINEAR" }, "chartOptions": { "mode": "COLOR" } } } ] } }
This creates a dashboard titled "Dashboard for MQL chart (API)" in your project. The dashboard contains a chart called "Min/Max Compute Engine CPU Utilization", which shows two lines, one for the highest values and one for the lowest.
For more information about this example query, see Combining selections with
union
.
Creating a chart
You can put the dashboard JSON into a file and then pass the file to
gcloud beta monitoring dashboards create
or use curl
to post it to
https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards
.
For more examples, see Creating a dashboard.
For more information about using curl
, see Invoking curl
.
For general information about creating charts and dashboards, see
Managing dashboards by API. For reference material, see
Dashboards
.
Creating conditions for alerting policies
You use the alertPolicies.create
method to
programmatically create alerting policies.
The only difference between creating MQL-based alerting policies
and other alerting policies is the type of Condition
you use. Otherwise, you create these policies like any other alerting policy.
The following shows a simple MQL query for an alert-policy condition that tests for Compute Engine CPU utilization exceeding 15 percent:
fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'
For more information about the MQL condition
alert operation, see
Alerting policies with MQL.
Constructing the alerting policy
To build an alerting policy based on an MQL query, use the AlertPolicy
condition type MonitoringQueryLanguageCondition
.
The MonitoringQueryLanguageCondition
has the following structure:
{ "query": string, "duration": string, "trigger": { object (Trigger) } }
The value of the query
field is a MQL alerting-query string in
either concise or strict form. The examples in this document are in concise
form. For more information about strict form, see Strict-form
queries.
The duration
field specifies the length of time during which each
evaluation of the query must generate a true
value before the alerting policy
is triggered. For more information, see
Behavior of metric-based alerting policies.
The value must be a number of minutes, expressed in seconds; for example,
600s
for a 10-minute duration.
The trigger
field specifies how many time series must satisfy the condition
during the duration
period, expressed as a count or a percentage. The
default value is a count of 1. For more in information,
see Trigger
.
For the example alerting query, with a 10-minute duration and a trigger count of 1, the structure looks like the following:
{ "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'", "duration": "600s", "trigger" : { "count": 1 } }
Use this structure as the value of a conditionMonitoringQueryLanguage
field in
a condition, which is in turn embedded in an alerting-policy structure.
For more information about these structures, see AlertPolicy
.
The following shows a complete minimal policy with a MonitoringQueryLanguageCondition
condition in JSON:
{ "displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)", "combiner":"OR", "conditions":[ { "displayName":"MQL-based utilization condition, API", "conditionMonitoringQueryLanguage": { "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'", "duration": "600s", "trigger" : { "count": 1 }, }, } ], }
Creating an alerting policy
To create the policy, you can put the alerting-policy JSON into a file and then
pass the file to gcloud alpha monitoring policies create
or use
curl
to post it to
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies
.
For more information about the Monitoring API for alerting policies, see Managing alerting policies by API.
For more information about using curl
, see Invoking curl
.
Invoking curl
Each curl
invocation includes a set of arguments,
followed by the URL of an API resource. The common arguments include
a Google Cloud project ID and an authentication token. These values
are represented here by the PROJECT_ID
and TOKEN
environment variables.
You might also have to specify other arguments, for example, to specify the type
of the HTTP request (for example, -X DELETE
). The default request is GET
,
so the examples don't specify it.
Each curl
invocation has this general structure:
curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>
To use curl
, you must specify your project ID and an access
token. To reduce typing and errors, you can put these into environment variables
as pass them to curl
that way.
To set these variables, do the following:
Create an environment variable to hold the ID of your scoping project of a metrics scope. These steps call the variable
PROJECT_ID
:PROJECT_ID=a-sample-project
Authenticate to the Google Cloud CLI:
gcloud auth login
Optional. To avoid having to specify your project ID with each
gcloud
command, set your project ID as the default by using gcloud CLI:gcloud config set project ${PROJECT_ID}
Create an authorization token and capture it in an environment variable. These steps call the variable
TOKEN
:TOKEN=`gcloud auth print-access-token`
You have to periodically refresh the access token. If commands that worked suddenly report that you are unauthenticated, reissue this command.
To verify that you got an access token, echo the
TOKEN
variable:echo ${TOKEN} ya29.GluiBj8o....