Oracle Cloud Infrastructure Documentation

Monitoring Query Language (MQL) Reference

This topic describes the components that appear in (Monitoring service) The syntax used for metric and alarm queries. (MQL) expressions, the order that they appear in, and valid values.

(Monitoring service) Monitoring Query Language. The syntax used for metric and alarm queries. In the Console, MQL syntax of queries is displayed in Advanced Mode. 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:

  • (Monitoring service) A measurement related to health, capacity, or performance of a given resource. Example: CpuUtilization
  • (Monitoring service) The time window used to convert the given set of raw data points. Example: 5 minutes
  • (Monitoring service) A qualifier provided in a metric definition. Example: Resource identifier (resourceId), provided in the definitions of oci_computeagent metrics., as one or more name-value pairs (optional)
  • grouping function (optional)
  • The aggregation function applied to the given set of raw data points. Example: SUM
  • 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 The trigger rule and query to evaluate and related configuration, such as notification details to use when the trigger is breached. Alarms passively monitor your cloud resources using metrics in Monitoring. 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.

When nesting queries, the query components appear in the following order (boldface components are required):

(metric[interval]{dimensionname="dimensionvalue"}.groupingfunction.statistic).groupingfunction.statistic

An example of a nested query is a grouped count of hosts with up time greater than zero, where the alarm query to identify these hosts is defined within parentheses:

(metric[1h].groupBy(host).min() > 0).grouping().count()

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 The cloud objects that your company's employees create and use when interacting with Oracle Cloud Infrastructure.. 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 (Monitoring service) A set of references, qualifiers, and other information provided by a metric namespace for a given metric..

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

The Monitoring Query Language (MQL) syntax (Advanced Mode in the Console) supports the following range of values for interval

1m-60m (also, 1h)

The Interval option in the Console (Basic Mode) supports the following range of values: 

  • 1m - 1 minute
  • 5m - 5 minutes
  • 1h - 1 hour
Note

For metric queries, the (Monitoring service) The time window used to convert the given set of raw data points. Example: 5 minutes you select drives the default (Monitoring service) The period between time windows, or the regularity at which time windows shift. Example: 1 minute of the request, which determines the maximum time range of data returned.

Maximum time range returned for a query

For more information about the resolution parameter as used in metric queries, see SummarizeMetricsData.

For alarm queries, the specified (Monitoring service) The time window used to convert the given set of raw data points. Example: 5 minutes has no effect on the (Monitoring service) The period between time windows, or the regularity at which time windows shift. Example: 1 minute 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 Aggregates all query results.

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) Sets the trigger condition as absence of the specified metric. (Applies to comparison operation queries only. 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