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

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, groupBy(availabilityDomain) groups results by availability domain so that results from each availability domain are together.

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, 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