Oracle Cloud Infrastructure Documentation

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

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: 

Note

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)
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 more information about the resolution parameter as used in metric queries, see SummarizeMetricsData.

Maximum time range returned for a query

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.

See examples of returned data

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

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.

Surround the dimension value with double quotes ("dimensionvalue"). Example dimension name-value pair for filtering by availability domain: availabilityDomain = "VeBZ:PHX-AD-1"

Multiple Dimension Name-Value Pairs

Specify multiple dimension name-value pairs in an MQL expression.

To specify multiple dimension name-value pairs in an MQL expression, separate each pair with a comma.

Syntax:

metric[interval]{dimensionname1="dimensionvalue1", dimensionname2="dimensionvalue2"}.groupingfunction.statistic

Multiple Values for a Dimension

Specify multiple values for a dimension name in an MQL expression.

Note

Multiple values per dimension name is available in MQL expressions only, using Advanced mode in the OCI Console.

To specify multiple values for a given dimension in an MQL expression, separate values with a pipe (|) character and update the query to use fuzzy matching (=~).

Syntax:

metric[interval]{dimensionname=~"dimensionvalue1|dimensionvalue2"}.groupingfunction.statistic

Fuzzy Matching

Specify approximate ("fuzzy") matches to dimension values in an MQL expression.

Note

Fuzzy matching is available in MQL expressions only, using Advanced mode in the OCI Console.

In place of the equals sign (=) between the dimension name and set of values, use the following comparison operator.

Comparison operator Description
=~ (equals sign followed by tilde) Approximately equal to; use for fuzzy matches

Update the set of dimension values using one or more of the following characters.

Value Fuzzy Match Character Description
* (asterisk) Wildcard, indicating zero to many characters.
|(pipe) OR operand for dimension values.

Example: Query for CPU utilization of test compute instances in Ashburn or Phoenix regions that use the “myshape” shape (fuzzy matching for three dimension value sets).

CpuUtilization [1m]{region =~ "us-ashburn-1|us-phoenix-1", resourceDisplayName =~ "test*", shape =~ "myshape"}.mean()

Excluding Values

Filter out (exclude) dimension values in an MQL expression.

Note

Filtering out values is available in MQL expressions only, using Advanced mode in the OCI Console.

In place of the equals sign (=) between the dimension name and set of values, use one of the following comparison operators.

Comparison operator Description
!= (exclamation point followed by equals sign) Not equal to; use to filter out a single dimension value.
!~ (exclamation point followed by tilde) Not equal to; use to filter out multiple dimension values (where wildcards or OR operands are used).

If using the !~ comparison operator, then update the set of dimension values using one or more of the following characters.

Value Fuzzy Match Character Description
* (asterisk) Wildcard, indicating zero to many characters.
|(pipe) OR operand for dimension values.

Example 1 (Single Value): Query for CPU utilization, excluding the Ashburn region.

CpuUtilization [1m]{region != "us-ashburn-1"}.mean()

Example 2 (Multiple Values): Query for CPU utilization, excluding both the Ashburn and Phoenix regions.

CpuUtilization [1m]{region !~ "us-ashburn-1|us-phoenix-1"}.mean()

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) Note: If groupBy is used, then dimensions are ignored.

Aggregates query results by group (dimension or resource group).

For example, groupBy(availabilityDomain) groups results by availability domain so that results from each availability domain are together.

grouping() Aggregate Metric Streams Note: If grouping() (Aggregate Metric Streams) is used, then only one stream is tracked. Do not use grouping() with split notifications.

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.
first() (not available) For each interval, returns the value with the earliest timestamp.
increment() (not available) Returns the per-interval change.
last() (not available) For each interval, returns the value with the latest timestamp.
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, 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.

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