This topic describes the components that appear in Monitoring Query Language (MQL) expressions, the order that they appear in, and valid values.
MQL syntax governs expressions for querying metrics that are published to the Monitoring service. In the Console, MQL expressions appear in Advanced Mode. If you don't need to aggregate results by group or to use other advanced query functionality, then you can create simpler versions of metric queries using Basic Mode in the Console.
An MQL expression includes the following components:
The query components appear in the following order (boldface components are required):
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic
Comparison operation queries used for alarms can take the following formats (boldface components are required):
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic
(where the statistic is absent()
)metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic operator value
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic operator (value1, value2)
You can nest alarm queries and metric queries.
Note
Nested alarm queries are not currently supported in the Console. Use the API to create alarms with nested queries.
In a nested query, the alarm portion appears at the beginning (surrounded with parentheses), followed by the grouping function (optional) and the statistic. The following syntax indicates required components using boldface type.
(metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic).groupingfunction.statistic
Example 1: The number of hosts with CPU utilization greater than 80 percent:
(CpuUtilization[1m].max() > 80).grouping().sum()
Example 2: The number of availability domains with a success rate lower than 0.99 :
(SuccessRate[1m].groupBy(availabilityDomain).mean() < 0.99).grouping().sum()
The metric component of the query appears before the interval.
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic
Valid values for metric depend on the resource . An example of a metric is CpuUtilization
, sent by Compute instances. For a list of supported resources with links to their metric references, see Supported Services. You can also use the ListMetrics operation to find metrics sent by a particular service, such as the Compute service. This operation returns metric definitions .
The interval component of the query appears between the metric and statistic (before the optional dimension namevalue pair and grouping function).
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic
The Monitoring Query Language (MQL) syntax (Advanced Mode in the Console) supports the following range of values for interval:
1m
60m
(also, 1h
)
The Interval option in the Console (Basic Mode) supports the following range of values:
For metric queries, the interval you select drives the default resolution of the request, which determines the maximum time range of data returned.
For more information about the resolution parameter as used in metric queries, see SummarizeMetricsData.
The maximum time range returned for a metric query depends on the resolution. By default, for metric queries, the resolution is the same as the query interval. The maximum time range is calculated using the current time, regardless of any specified end time. Following are the maximum time ranges returned for each interval selection available in the Console.
Interval  Default resolution (metric queries)  Maximum time range returned 

1h  1 hour  90 days 
5m  5 minutes  30 days 
1m  1 minute  7 days 
Example 1: Oneminute interval and resolution up to the current time, sent at 10:00 on January 8th. No resolution or end time is specified, so the resolution defaults to the interval value of 1m
, and the end time defaults to the current time (20190108T10:00:00.789Z
). This request returns a maximum of 7 days of metric data points. The earliest data point possible within this sevenday period would be 10:00 on January 1st (20190101T10:00:00.789Z
).
Example 2: Fiveminute interval with oneminute resolution up to two days ago, sent at 10:00 on January 8th. Because the resolution drives the maximum time range, a maximum of 7 days of metric data points is returned. While the end time specified was 10:00 on January 6th (20190106T10:00:00.789Z
), the earliest data point possible within this sevenday period would be 10:00 on January 1st (20190101T10:00:00.789Z
). Therefore, only 5 days of metric data points can be returned in this example.
For alarm queries, the specified interval has no effect on the resolution of the request. The only valid value of the resolution for an alarm query request is 1m
. For more information about the resolution parameter as used in alarm queries, see Alarm.
The dimensionname="dimensionvalue" component of the query appears between the interval and statistic (before the optional grouping function).
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic
Surround the dimension value with double quotes. Example dimension namevalue pair for filtering by availability domain: availabilityDomain = "VeBZ:PHXAD1"
You can specify multiple dimension namevalue pairs. Place each pair within the brackets and separate the pairs with commas.
Valid values for dimensionname depend on the metric. An example of a dimension name is resourceDisplayName
, included with the CpuUtilization
metric sent by Compute instances. For a list of supported resources with links to their metric references, including dimensions, see Supported Services. You can also use the ListMetrics operation to find metrics (and their dimensions) sent by a particular application or service, such as the Compute service.
The groupingfunction component of the query appears between the interval and statistic (after the optional dimension namevalue pair).
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic
Valid grouping functions are as follows.
Grouping function (MQL expression; Advanced Mode in the Console)  Grouping function option (Basic Mode in the Console)  Description 

groupBy()

(not available) 
Aggregates query results by group (dimension or resource group). For example, 
grouping()

Aggregate Metric Streams  Aggregates all query results. 
The statistic component of the query appears after the interval and optional dimension namevalue pair and grouping function.
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic
Valid statistics are as follows.
Statistic (MQL expression; Advanced Mode in the Console)  Statistic option (Basic Mode in the Console)  Description 

absent()

(see absent)  Returns 1 if the metric is not present in the whole interval. Otherwise, returns 0. Useful for defining alarms. 
avg()

(not available)  Returns the value of Sum divided by Count during the specified time period. Identical to mean() . 
count()

COUNT  Returns the number of observations received in the specified time period. 
increment()

(not available)  Returns the perinterval change. 
max()

MAX  Returns the highest value observed during the specified time period. 
mean()

MEAN  Returns the value of Sum divided by Count during the specified time period. 
min()

MIN  Returns the lowest value observed during the specified time period. 
percentile()

P50 P90 P95 P99 P99.9 
Returns the estimated value of the specified percentile. Valid values are greater than 0.0 and less than 1.0. For example, 
rate()

RATE  Returns the perinterval average rate of change. The unit is persecond. 
sum()

SUM  Returns all values added together. 
The operator value component of the query appears after the statistic in threshold alarm queries. Either one or two values are needed, depending on the operator:
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic operator value
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic operator (value1, value2)
Valid operators are as follows.
Operator (MQL expression; Advanced Mode in the Console)  Operator option (Basic Mode in the Console)  Number of values 

>

greater than  1 
>=

greater than or equal to  1 
==

equal to  1 
!= (not equal to) 
(not available)  1 
<

less than  1 
<=

less than or equal to  1 
in (inclusive of specified values) 
between (inclusive of specified values)  2 
not in (inclusive of specified values) 
outside (inclusive of specified values)  2 
Not applicable. See absent().  absent  0 