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.

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.

For alarms in the Console, the absent() statistic is listed under Operator. See Creating an Absence Alarm.

More information about absent() in the Console

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

Note

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.

Note

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.

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 (`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.
`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()

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 two hours, not generating any values.

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)