Oracle Cloud Infrastructure Documentation

Building Metric Queries

This topic describes how to query (Monitoring service) A measurement related to health, capacity, or performance of a given resource. Example: CpuUtilization for The cloud objects that your company's employees create and use when interacting with Oracle Cloud Infrastructure. of interest, create 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. from a given (Monitoring service) The expression to evaluate for returning aggregated data. A valid query includes a metric, statistic, and interval. In the Console, you can view a query in Basic Mode or Advanced Mode. The latter displays the Monitoring Query Language (MQL) syntax., and share Console charts.

Warning

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

Prerequisites

  • IAM policies: Querying metrics is part of monitoring. To monitor resources, you must be given the required type of access in a An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. The policy must give you access to the monitoring services as well as the resources being monitored. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization. you should work in. For more information on user authorizations for monitoring, see the Authentication and Authorization section for the related service: Monitoring or Notifications. For common policies that give groups access to metrics, see Let users view metric definitions in a compartment and Restrict user access to a specific metric namespace.
  • Metrics exist in Monitoring: The resources that you want to monitor must emit metrics to the Monitoring service.
  • Compute instances: To emit metrics, Compute instances must be monitoring-enabled. OracleCloudAgent software installation may also be required. For more information, see Enabling Monitoring for Compute Instances.

Working with Metric Queries

This section shows (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 of metric and alarm queries.

Use metric (Monitoring service) The expression to evaluate for returning aggregated data. A valid query includes a metric, statistic, and interval. In the Console, you can view a query in Basic Mode or Advanced Mode. The latter displays the Monitoring Query Language (MQL) syntax. to actively and passively monitor your cloud resources. Actively monitor with metric queries that you generate spontaneously, on demand. In the Console, update a chart to show data from multiple queries. Store queries you want to reuse. Passively monitor with alarms that add a condition, or trigger rule, to a metric query.

Metric query syntax (boldface elements are required): 

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

Threshold Alarm query syntax (boldface elements are required): 

metric[interval]{dimensionname=dimensionvalue}.groupingfunction.statistic alarmoperator alarmvalue

For supported parameter values, see Monitoring Query Language (MQL) Reference.

Example queries

For background information on metrics in Oracle Cloud Infrastructure, see Metrics Feature Overview.

Using the Console

To create a query
To change the time range
To filter results
To aggregate all results
To aggregate results by group
To edit a query using MQL syntax
To create an alarm from a query
To hide a query from the chart
To share a query

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use this API operation to find metric names and dimensions (view (Monitoring service) A set of references, qualifiers, and other information provided by a metric namespace for a given metric.): 

ListMetrics

Use this API operation to query metrics by name (and optionally filter by (Monitoring service) A qualifier provided in a metric definition. Example: Resource identifier (resourceId), provided in the definitions of oci_computeagent metrics.):

SummarizeMetricsData