Monitoring Overview

The Monitoring service uses metrics  to monitor resources and alarms  to notify you when these metrics meet alarm-specified triggers.

Metrics are emitted to the Monitoring service as raw data points , or timestamp-value pairs, along with dimensions  and metadata. Metrics come from a variety of sources:

• Resource metrics automatically posted by Oracle Cloud Infrastructure resources . For example, the Compute service posts metrics for monitoring-enabled Compute instances through the oci_computeagent namespace. One such metric is CpuUtilization. See Supported Services and Viewing Default Metric Charts.
• Custom metrics published using the Monitoring API.
• Data sent to new or existing metrics using Service Connector Hub.

Metric data posted to the Monitoring service is only presented to you or consumed by the Oracle Cloud Infrastructure features that you enable to use metric data.

When you query a metric, the Monitoring service returns aggregated data according to the specified parameters. You can specify a range (such as the last 24 hours), statistic , and interval . The Console displays one monitoring chart per metric for selected resources. The aggregated data in each chart reflects your selected statistic and interval. API requests can optionally filter by dimension  and specify a resolution . API responses include the metric name along with its source compartment and metric namespace . You can feed the aggregated data into a visualization or graphing library.

Metric and alarm data is accessible via the Console, CLI, and API. For retention periods, see Storage Limits.

The Alarms feature of the Monitoring service publishes alarm messages  to configured destinations managed by the Notifications service. Each destination is a topic  with a set of subscribers . For more information about the Notifications service, see Notifications Overview.

The following concepts are essential to working with Monitoring.

aggregated data

The result of applying a statistic and interval to a selection of raw data points for a given metric. For example, you can apply the statistic max and interval 1h (one hour) to the last 24 hours of raw data points for the metric CpuUtilization. Aggregated data is displayed in default metric charts in the Console. You can also build metric queries for specific sets of aggregated data. For instructions, see Viewing Default Metric Charts and Building Metric Queries.

alarm

The alarm query to evaluate and the notification destination to use when the alarm is in the firing state, along with other alarm properties. For instructions on managing alarms, see Managing Alarms.

alarm query

The Monitoring Query Language (MQL) expression to evaluate for the alarm. An alarm query must specify a metric, statistic, interval, and a trigger rule (threshold or absence). The Alarms feature of the Monitoring service interprets results for each returned time series as a Boolean value, where zero represents false and a non-zero value represents true. A true value means that the trigger rule condition has been met. For more information, see Building Metric Queries and the query attribute description in the Alarm API reference.

data point

A timestamp-value pair for the specified metric. Example: 2018-05-10T22:19:00Z, 10.4

A data point is either raw or aggregated. Raw data points are posted by the metric namespace to the Monitoring service using the PostMetricData operation. The frequency of the data points posted varies by metric namespace. For example, your custom namespace might send data points for a given metric at a 20-second frequency.

Aggregated data points are the result of applying a statistic and interval to raw data points. The interval of the aggregated data points is determined by the SummarizeMetricsData request. For example, a request specifying the statistic sum and interval 1h (one hour) returns a sum value for each hour of available raw data points for the given metric.

dimension

A qualifier provided in a metric definition. Example: Resource identifier (resourceId), provided in the definitions of oci_computeagent metrics. Use dimensions to filter or group metric data. Example dimension name-value pair for filtering by availability domain: availabilityDomain = "VeBZ:PHX-AD-1"

frequency

The time period between each posted raw data point for a given metric. (Raw data points are posted by the metric namespace to the Monitoring service.) While frequency varies by metric, default service metrics typically have a frequency of 60 seconds (that is, one data point posted per minute). See also resolution.

interval

The time window used to convert the given set of raw data points.

The timestamp of the aggregated data point corresponds to the end of the time window during which raw data points are assessed. For example, for a five-minute interval, the timestamp "2:05" corresponds to the five-minute time window from 2:00:n to 2:05:00.

The following example query specifies a 5-minute interval. CpuUtilization[5m].max() For supported values, see Monitoring Query Language (MQL) Reference.

Note

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.

To specify an interval value that is not available in Basic Mode in the Console, such as 12 hours, switch to Advanced Mode.

See also resolution.

message

The content that the Alarms feature of the Monitoring service publishes to topics in the alarm’s configured notification destinations. A message is sent when the alarm transitions to another state, such as from "OK" to "FIRING." For more information about messages, see How Monitoring Works.

metadata

A reference provided in a metric definition. Example: unit (bytes), provided in the definition of the oci_computeagent metricDiskBytesRead. Use metadata to determine additional information about a given metric. For metric definitions, see Supported Services.

metric

A measurement related to health, capacity, or performance of a given resource. Example: The oci_computeagent metricCpuUtilization, which measures usage of a Compute instance. For metric definitions, see Supported Services.

Note

Metric resources do not have OCIDs .

metric definition

A set of references, qualifiers, and other information provided by a metric namespace for a given metric. For example, the oci_computeagent metric DiskBytesRead is defined by dimensions (such as resource identifier) and metadata (specifying bytes for unit) as well as identification of its metric namespace (oci_computeagent). Each posted set of data points carries this information. Use the ListMetricData API operation to get metric definitions. For metric definitions, see Supported Services.

metric namespace

Indicator of the resource , service, or application that emits the metric. Provided in the metric definition. For example, the CpuUtilization metric definition emitted by the Oracle Cloud Agent software on Compute instances  lists the metric namespace oci_computeagent as the source of the CpuUtilization metric. For metric definitions, see Supported Services.

metric stream

An individual set of aggregated data for a metric. A stream can be either specific to a single resource  or aggregated across all resources in the compartment. Within a metric chart in the Console, each metric stream is represented as a line. By default, metric streams are resource-specific, so the chart displays a line for each resource. If you choose to aggregate all metric streams, then the chart displays one line for all resources.

notification destination

Protocol and other details for sending messages when the alarm transitions to another state, such as from "OK" to "FIRING." The details and setup may vary by destination service. For the Notifications service, each destination includes a topic and subscription protocol (such as PagerDuty). For more information about messages, topics, and subscriptions, see Notifications Overview.

Oracle Cloud Agent software

Software that allows a Compute instance to post raw data points to the Monitoring service. Automatically installed with the latest versions of supported images. See Enabling Monitoring for Compute Instances.

query

The Monitoring Query Language (MQL) expression to evaluate for returning aggregated data. The query must specify a metric, statistic, and interval. For more information, see Building Metric Queries.

resolution

The period between time windows, or the regularity at which time windows shift. For example, use a resolution of 1m to retrieve aggregations every minute.

To specify a non-default resolution that differs from the interval, use the SummarizeMetricsData operation.

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
1d	1 day	90 days
1h	1 hour	90 days
5m	5 minutes	30 days
1m	1 minute	7 days

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.

As shown in the following illustration, resolution controls the start time of each aggregation window relative to the previous window while interval controls the length of the windows. Both requests apply the statistic max to the data within each five-minute window (from the interval), resulting in a single aggregated data point representing the highest CPUutilization counter for that window. Only the resolution value differs. This resolution changes the regularity at which the aggregation windows shift, or the start times of successive aggregation windows. Request A does not specify a resolution and thus uses the default value equal to the interval (5 minutes). This request's five-minute aggregation windows are thus taken from the sets of data points emitted from 0:n to 5:00, 5:n to 10:00, and so forth. Request B specifies a 1-minute resolution, so its five-minute aggregation windows are taken from the set of data points emitted every minute from 0:n to 5:00, 1:n to 6:00, and so forth.

resource group

A custom string provided with a custom metric that can be used as a filter or to aggregate results. The resource group must exist in the definition of the posted metric. Only one resource group can be applied per metric.

statistic

The aggregation function applied to the given set of raw data points. For supported statistics, see Monitoring Query Language (MQL) Reference.

suppression

A configuration to avoid publishing messages during the specified time range. Useful for suspending alarm notifications during system maintenance. Each suppression applies to a single alarm. In the Console, you can apply one definition of a suppression to multiple alarms. The result is an individual suppression for each alarm. For instructions on suppressing alarms, see To suppress alarms.

trigger rule

The condition that must be met for the alarm to be in the firing state. A trigger rule can be based on a threshold or absence of a metric.

The Monitoring service is available in all Oracle Cloud Infrastructure commercial regions. See About Regions and Availability Domains for the list of available regions, along with associated locations, region identifiers, region keys, and availability domains.

The following services have resources or components that can emit metrics to Monitoring:

• API Gateway - see API Gateway Metrics
• Big Data - see View Cluster Metrics
• Block Storage - see Block Volume Metrics
• Blockchain Platform - see Blockchain Platform Metrics

• Compute - see these topics:

  • Compute Instance Metrics
  • Instance Pool Metrics
  • Infrastructure Health Metrics
  • Compute Management Metrics
• Container Engine for Kubernetes - see Container Engine for Kubernetes Metrics
• Data Catalog - see Data Catalog Metrics
• Data Integration - see Data Integration Metrics
• Database - see Database Metrics
• Digital Assistant - see Digital Assistant Metrics
• DNS - see DNS Metrics
• Events - see Events Metrics
• Email Delivery - see Email Delivery Metrics
• File Storage - see File System Metrics
• Functions - see Function Metrics
• Health Checks - see Health Checks Metrics
• Integration - see Viewing Message Metrics
• Load Balancing - see Load Balancing Metrics
• Management Agent - see Management Agent Metrics
• MySQL Database - see MySQL Database Metrics

• Networking - see these topics:

  • VNIC Metrics
  • FastConnect Metrics
  • VPN Connect Metrics
  • Service Gateway Metrics
• NoSQL Database Cloud - see Service Metrics
• Notifications - see Notifications Metrics
• Object Storage - see Object Storage Metrics
• OS Management - see OS Management Metrics
• Streaming - see Streaming Metrics
• Vault - see Vault Metrics
• WAF - see WAF Metrics

Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to identify your resources, see Resource Identifiers.

You can access the Monitoring service using the Console (a browser-based interface) or the REST API. Instructions for the Console and API are included in topics throughout this guide. For a list of available SDKs, see Software Development Kits and Command Line Interface.

Console: To access Monitoring using the Console, you must use a supported browser. You can use the Console link at the top of this page to go to the sign-in page. You will be prompted to enter your cloud tenant, your user name, and your password. Open the navigation menu. Under Solutions and Platform, go to Monitoring.

API: To access Monitoring through APIs, use Monitoring API for metrics and alarms and Notifications API for notifications (used with alarms).

You can move alarms from one compartment to another. When you move an alarm to a new compartment, its associated metrics remain where they are. After you move the alarm to the new compartment, inherent policies apply immediately and affect access to the alarm through the Console. For more information on moving resources to other compartments, see To move a resource to a different compartment.

Administrators: 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. For a common alarms policy, see Let users view alarms. To authorize resources, such as instances, to make API calls, add the resources to a dynamic group. Use the dynamic group's matching rules to add the resources, and then create a policy that allows that dynamic group access to metrics. See Let instances make API calls to access monitoring metrics in the tenancy.

See Monitoring Limits for a list of applicable limits and instructions for requesting a limit increase.

Other limits include the following.