Monitoring Query Language (MQL) Reference
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.
Components in an MQL Expression
An MQL expression includes the following components:
- metric
- interval
- dimensions , as one or more name-value pairs (optional)
- grouping function (optional)
- statistic
- comparison operation (optional). Useful for defining alarms.
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 isabsent()
)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.
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()
Metric Query Component
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 .
Interval Query Component
The interval component of the query appears between the metric and statistic (before the optional dimension name-value pair and grouping function).
metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic
Supported values for interval depend on the specified time range in the metric query (not applicable to alarm queries). More interval values are supported for smaller time ranges. For example, if you select one hour for the time range, then all interval values are supported. If you select 90 days for the time range, then only the 1h or 1d interval values are supported.
The Monitoring Query Language (MQL) syntax (Advanced Mode in the Console) supports the following range of values for interval:
1m
-60m
, 1h
-24h
, 1d
The Interval option in the Console (Basic Mode) supports the following range of values:
Valid alarm intervals depend on the frequency at which the metric is emitted. For example, a metric emitted every five minutes requires a 5-minute alarm interval or higher. Most metrics are emitted every minute, which means most metrics support any alarm interval. To determine valid alarm intervals for a given metric, check the relevant service's metric reference.
- Auto (Service Metrics page only) - automatic interval
selection based on time range:
Time range Interval when Auto is selected 6 hours or less 1 minute 36 hours or less (but more than 6 hours) 5 minutes More than 36 hours 1 hour - 1 minute (Service Metrics page) / 1m (Create Alarm and Metrics Explorer pages)
- 5 minutes (Service Metrics page) / 5m (Create Alarm and Metrics Explorer pages)
- 1 hour (Service Metrics page) / 1h (Create Alarm and Metrics Explorer pages)
- 1 day (Service Metrics page) / 1d (Create Alarm and Metrics Explorer pages)
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 (Basic mode). To specify an interval value that is not available in Basic Mode in the Console, such as 12 hours, switch to Advanced mode.
Interval | Default resolution (metric queries) | Maximum time range returned |
---|---|---|
1 minute (Service Metrics page) 1m (Create Alarm and Metrics Explorer pages) Auto (Service Metrics page)*, when the selected period of time is 6 hours or less |
1 minute | 7 days |
5 minutes (Service Metrics page) 5m (Create Alarm and Metrics Explorer pages) Auto (Service Metrics page)*, when the selected period of time is more than 6 hours and less than 36 hours |
5 minutes | 30 days |
1 hour (Service Metrics page) 1h (Create Alarm and Metrics Explorer pages) Auto (Service Metrics page)*, when the selected period of time is more than 36 hours |
1 hour | 90 days |
1 day (Service Metrics page) 1d (Create Alarm and Metrics Explorer pages) |
1 day | 90 days |
* The maximum time range returned when Auto is selected for Interval (Service Metrics page only) is determined by the automatic interval selection. The automatic interval selection is based on the selected period of time.
To specify a non-default resolution that differs from the interval, use the SummarizeMetricsData operation.
Example 1: One-minute 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 (2019-01-08T10:00:00.789Z
). This request returns a maximum of 7 days of metric data points. The earliest data point possible within this seven-day period would be 10:00 on January 1st (2019-01-01T10:00:00.789Z
).
Example 2: Five-minute interval with one-minute 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 (2019-01-06T10:00:00.789Z
), the earliest data point possible within this seven-day period would be 10:00 on January 1st (2019-01-01T10: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.
Dimension Query Component
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 name-value pair for filtering by availability domain: availabilityDomain = "VeBZ:PHX-AD-1"
You can specify multiple dimension name-value 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.
Grouping Function Query Component
The groupingfunction component of the query appears between the interval and statistic (after the optional dimension name-value 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 |
Returns the combined value of all metric streams for the selected statistic. |
Statistic Query Component
The statistic component of the query appears after the interval and optional dimension name-value 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 per-interval 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 per-interval average rate of change. The unit is per-second. |
sum()
|
SUM | Returns all values added together. |
Operator and Value Query Component
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 |