Understand the syntax of Monitoring Query Language (MQL) expressions and review valid values for interval, statistic, and predicate operators in MQL expressions.
MQL syntax governs expressions for querying metrics that are published to the Monitoring service. MQL expressions define queries (including alarm queries). MQL acts on aggregated data.
The following diagram depicts required components and common optional components.
Note
Some components can appear in an MQL expression multiple times. For example, you can use two grouping functions (as in groupBy(), followed by a statistic, followed by grouping()). You can also nest queries.
To select the absent() statistic in the Console, see the following page-specific instructions.
Create Alarm or Edit alarm page: In Basic mode, select absent from Operator under Trigger rule. In Advanced mode (select Switch to Advanced Mode), update the MQL expression.
Metrics Explorer page: Select Advanced mode to use MQL.
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 interval values between 1 hour and 1 day are supported.
Select an alarm interval based on the frequency at which the metric is emitted. For example, a metric emitted every five minutes requires a 5-minute alarm interval or greater. Most metrics are emitted every minute, which means most metrics support any alarm interval. To determine valid alarm intervals for a specific metric, check the relevant service's metric reference.
Example: One-Minute Interval (1m)
CpuUtilization[1m].mean()
Following are valid intervals for MQL expressions: 1m-60m, 1h-24h, 1d
For metric queries, the interval you select drives the default resolution of the request, which determines the maximum time range of data returned.
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 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).
Interval
Default resolution (metric queries)
Maximum time range returned
1 minute
Auto (Service Metrics page)*, when the selected period of time is 6 hours or less
1 minute
7 days
5 minutes
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
Auto (Service Metrics page)*, when the selected period of time is more than 36 hours
1 hour
90 days
1 day
1 day
90 days
* The maximum time range returned when you select Auto 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.
One-minute interval and resolution up to the current time, sent at 10:00 on January 8. 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 (2023-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 1 (2023-01-01T10:00:00.789Z).
Example 2 for Returned Data
Five-minute interval with one-minute resolution up to two days ago, sent at 10:00 on January 8. 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 6 (2023-01-06T10:00:00.789Z), the earliest data point possible within this seven-day period would be 10:00 on January 1 (2023-01-01T10:00:00.789Z). Therefore, only 5 days of metric data points can be returned in this example.
Statistic 🔗
The statistic is the aggregation function applied to the set of raw data points at the specified interval.
Valid values range from one minute (1m) to three days (3d or 72h). Specify the amount of time in the absence detection period using a number and unit (m, h, or d for minute, hour, or day).
For each interval, returns the value with the latest timestamp in the specified interval.
max()
Max
Returns the highest value observed during the specified interval.
mean()
Mean
Returns the value of Sum divided by Count during the specified interval.
min()
Min
Returns the lowest value observed during the specified interval.
percentile(p)
P50
P90
P95
P99
P99.9 (Service Metrics page only)
Returns the estimated value of the specified percentile (p when using SDK, CLI, or API) during the specified interval. Valid values are greater than 0.0 and less than 1.0.
For example, percentile(0.8) returns the value of the 80th percentile.
rate()
Rate
Returns the per-interval average rate of change. The unit is per-second.
absent() description: Returns true (1) if the metric is absent for the entire interval.
Returns false (0) if the metric is present during the interval.
Is ignored after the absence detection period, not generating any values.
Valid values range from one minute (1m) to three days (3d or 72h). Specify the amount of time in the absence detection period using a number and unit (m, h, or d for minute, hour, or day).
The following arithmetic operators are supported in MQL expressions.
Operator
Description
+
Add
-
Subtract
*
Multiply
/
Divide
%
Modulo (divide and return remainder)
Join Queries 🔗
Use the && (AND) and || (OR) operators to join queries. Multiple joined queries act as a single query.
Note
The && (AND) and || (OR) operators can only be used between queries. Don't use them between dimension sets. For example, the following query is invalid: CpuUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2" || resourceDisplayName = "test"}.mean()
Join operator
Description
&&
AND: Join queries. Returns true if both operands are true. Returns false otherwise.
||
OR: Join queries. Returns true if either operand is true, or if both operands are true. Returns false otherwise.
Example 1: Join queries with OR. Return true if CPU utilization data point is in fault domain 1 or 2 OR memory utilization data point is in fault domain 1 or 2.
Example 2: Join alarm queries with AND. Trigger the alarm (transition to firing state) only when both queries are true: At least one error exists AND the mean error is greater than half.
Example 3: Join alarm queries with AND. Trigger the alarm (transition to firing state) only when both queries are true: For smaller reads (0 to 8 Kilobytes), the 50th percentile of requests exceeds 100 AND the mean latency is less than 0.01.