Monitoring Query Language (MQL) Reference
Understand the syntax of Monitoring Query Language (MQL) expressions and review valid values for interval, statistic, and predicate operators in MQL expressions.
For information about editing MQL , see Editing the MQL Expression for a Query.
MQL Syntax
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 provides a simple depiction of required components and common optional components.
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.
For alarms in the Console, the absent()
statistic is listed under Operator. See Creating an Absence Alarm.
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 (click Switch to Advanced Mode), update the MQL expression.
- Metrics Explorer page: Click Advanced mode to use MQL.
- Service Metrics page: Open the query in Metrics Explorer, then click Advanced mode to use MQL.
For information about reading railroad diagrams, see Reading Railroad Diagrams.
Valid Values for MQL Expressions
Review valid values for interval, statistic, and predicate operators in MQL expressions.
Interval
Along with interval, consider the resolution and time range.
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 instructions, see Selecting the Interval for a Query.
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.
To specify a nondefault resolution that differs from the interval, see Selecting a Nondefault Resolution for a Query.
- Example 1 for Returned Data
- 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.
- Example: Mean Statistic
-
CpuUtilization[1m].mean()
For instructions, see Selecting the Statistic for a Query.
Following are valid statistics.
Statistic (MQL expression) | Statistic option (Basic Mode in the Console) | Description |
---|---|---|
absent()
|
(see absent operator) |
Absence predicate. 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 two hours, not generating any values. Use this statistic in basic queries as well as absence alarms. See Specifying a Predicate in a Query. |
avg()
|
(not available) | Returns the value of Sum divided by Count during the specified interval. Identical to mean() . |
count()
|
Count | Returns the number of observations received in the specified interval. |
first() |
(not available) | For each interval, returns the value with the earliest timestamp in the specified interval. |
increment()
|
(not available) | Returns the per-interval change. |
last() |
(not available) | 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 ( For example, |
rate()
|
Rate | Returns the per-interval average rate of change. The unit is per-second. |
sum()
|
Sum | Returns all values added together, per interval. |
Predicate Operators
The predicate component keeps only specified values from the metric streams. Use a predicate operator to define a threshold or absence.
- Example 1: Mean CPU Utilization Greater than 80 Percent (Threshold Predicate)
-
CpuUtilization[1m].mean() > 80
- Example 2: Mean CPU Utilization Between 60 and 80 Percent (Threshold Predicate)
-
CpuUtilization[1m].mean() in (60, 80)
- Example 3: Errors Greater than 1 (Threshold Predicate)
-
ServiceConnectorHubErrors[1m].count() > 1
- Example 4: 90th Percentile CPU Utilization Greater than 85 (Threshold Predicate, Selecting an Availability Domain and Grouping by Pool)
-
CpuUtilization[1m]{availabilityDomain="VeBZ:PHX-AD-1"}.groupBy(poolId).percentile(0.9) > 85
- Example 5: No CPU Utilization Metrics Emitted (Absence Predicate)
-
CpuUtilization[1m]{resourceId = "<resource_identifier>"}.groupBy(resourceId).absent()
For instructions, see Specifying a Predicate in a Query.
Following are valid operators.
Operator (MQL expression) | Operator option (Basic Mode in the Console) | Comments |
---|---|---|
> |
greater than | |
>= |
greater than or equal to | |
== |
equal to | |
!= |
(not available) | Not equal to. |
<
|
less than | |
<=
|
less than or equal to | |
in |
between (inclusive of specified values) | Inclusive of the two specified values. |
not in |
outside (inclusive of specified values) | Inclusive of the two specified values. |
(see absent() statistic) | absent |
Absence predicate. 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 two hours, not generating any values. Use this statistic in basic queries as well as absence alarms. See Specifying a Predicate in a Query. |
For alarm instructions, see Creating a Threshold Alarm and Creating an Absence Alarm.
Arithmetic Operators
The following arithmetic operators are supported in MQL expressions.
+
(addition)-
(subtraction)*
(multiplication)/
(division)%
(modulo)