Building Metric Queries

This topic describes how to query metrics  for resources  of interest, create alarms  from a given query , 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 policy  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 compartment  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. Oracle Cloud Agent software installation may also be required. For more information, see Enabling Monitoring for Compute Instances.

Working with Metric Queries

This section shows MQL  syntax of metric and alarm queries.

Use metric queries  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.

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

Example queries

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 metric definitions ): 

ListMetrics

Use this API operation to query metrics by name (and optionally filter by dimension ):

SummarizeMetricsData