You are currently viewing How to Retrieve OCI Metrics using the REST API

How to Retrieve OCI Metrics using the REST API

Introduction

The Oracle Cloud Infrastructure Monitoring service enables you to monitor your cloud resources using the Metrics and Alarms features actively and passively. The Monitoring service uses metrics to monitor resources and alarms to notify you when these metrics meet alarm-specified triggers.

Metric and alarm data is accessible via the Console, CLI, SDK, and API.

In this article, we look at how to access OCI Compute Metrics using the API.

Overview

Using the OCI Monitoring API to retrieve Metrics is straightforward – there is only one endpoint to be used with metric queries passed in the request body.

REST API Info

The REST API endpoint used to retrieve any kind of metrics is SummarizeMetricsData. Returns aggregated data that match the criteria specified in the request.

Compartment OCID is a required parameter and the request body must contain a single SummarizeMetricsDataDetails resource.

Transactions Per Second (TPS) per-tenancy limit for this operation: 10. If exceeded –an HTTP 429 TooManyRequests error will be received. Retry strategies can be implemented to manage these errors.

For important limits information, see Limits on Monitoring.

Important: Each OCI Region has its own API Endpoint for the Monitoring API, see Monitoring API Endpoints.

Metric Queries Info

When using the SummarizeMetricsData API, the request body must contain a SummarizeMetricsDataDetails resource. This request body must contain a query attribute which uses Monitoring Query Language (MQL) expressions to search for metric data points to aggregate. The query must specify a metric, statistic, and interval.

Construct your query to avoid exceeding limits on returned data. See MetricData Reference.

For details about Monitoring Query Language (MQL), see Monitoring Query Language (MQL) Reference. For available dimensions, review the metric definition for the supported service. See Supported Services.

Prerequisites when using the OCI APIs

Please make sure you have the following prepared before starting using the APIs:

  • tenancy_ocid: OCID of your tenancy. To get the value, see Required Keys and OCIDs. Example: tenancy.oc1..<unique_ID>
  • user_ocid: OCID of the user calling the API. To get the value, see Required Keys and OCIDs. Example: user.oc1..<unique_ID>
  • fingerprint: Fingerprint for the public key that was added to this user. To get the value, see Required Keys and OCIDs.
  • private_key: Contents of the private key file. You can open the file in an editor and copy the contents or use a command like pbcopy < ~/.oci/oci_api_key.pemThe key pair must be in PEM format. For instructions on generating a key pair in PEM format, see Required Keys and OCIDs.
  • passphrase: Passphrase used for the key. Only required if the key is encrypted.
  • region: An Oracle Cloud Infrastructure region. See Regions and Availability Domains. Example: eu-frankfurt-1
  • compartment_ocid: OCID of the compartment that will be used for the API calls. Example: compartment.oc1..<unique_ID>

Step by Step Example: Get OCI Compute Metrics

In this example, we’ll look at how to retrieve different kinds of metrics from an OCI Compute Instance.

OCI REST APIs Postman Workspace

There is an OCI REST APIs Workspace publicly available on Postman called “Oracle Cloud Infrastructure REST APIs” that you can fork. It can be found using the search bar:

Or it can be found on the Postman web portal as well OCI Rest API Workspace.

Setup Postman Collection & Environment

Step 1: Create a new Postman Workspace (or use an existing one)

Step 2: Fork the Monitoring API Collection in your Workspace

Step 3: Fork the OCI Credentials Environment in your Workspace

Step 4: Make sure you are in your Workspace where you forked the Monitoring API Collection and the OCI Credentials Environment

Step 5: Select the OCI Credentials environment

Step 6: Fill in all the fields from the OCI Credentials Environment with the info gathered in the prerequisites

Call the OCI Monitoring API

IMPORTANT – There are two URLs for the Monitoring API, one used for retrieving information and one for ingestion.

In the newly forked Monitoring API Collection, there are two variables for each URL:

Step 1: From the newly forked Monitoring API Collection, select the summarizeMetricsData endpoint:

IMPORTANT

  1. Make sure to change the Base URL Variable to the correct one: {{baseUrl}} rather than {{baseUrlIngestion}} which is used for data ingestion
  2. Uncheck compartmentIdInSubtree if not using for the whole tenancy. The parameter can only be set to true when compartmentId is the tenancy OCID.

Step 2: Add your query in the body of the request

This is a simple example on how to get the CPU Utilization on a 1-minute interval from a specific instance (specifying the resourceId dimension and the OCID of the Compute Instance) and a specific period of time (startTime and endTime):

{
  "namespace": "oci_computeagent",
  "query": "CpuUtilization[1m]{resourceId=ocid1.instance.oc1.eu-frankfurt-1.anthaaaaaaaaata}.max()",
  "startTime": "2021-12-17T08:00:00.00Z",
  "endTime": "2021-12-17T08:02:00.00Z"
}

Metric query syntax (bold elements are required):

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

The response will look something like this:

[
    {
        "namespace": "oci_computeagent",
        "resourceGroup": null,
        "compartmentId": "ocid1.compartment.oc1..aaaaaaaaaaaaaaaaa7a",
        "name": "CpuUtilization",
        "dimensions": {
            "instancePoolId": "Default",
            "resourceDisplayName": "webtest_ad2",
            "faultDomain": "FAULT-DOMAIN-3",
            "resourceId": "ocid1.instance.oc1.eu-frankfurt-1.antaaaaaaata",
            "availabilityDomain": "mDbm:EU-FRANKFURT-1-AD-2",
            "imageId": "ocid1.image.oc1.eu-frankfurt-1.aaaaaaaaaaawa",
            "region": "eu-frankfurt-1",
            "shape": "VM.Standard.E4.Flex"
        },
        "metadata": {
            "displayName": "CPU Utilization",
            "maxRange": "100",
            "unit": "Percent",
            "minRange": "0"
        },
        "resolution": null,
        "aggregatedDatapoints": [
            {
                "timestamp": "2021-12-17T08:00:00.000Z",
                "value": 6.106106106105956
            },
            {
                "timestamp": "2021-12-17T08:01:00.000Z",
                "value": 6.656656656656419
            },
            {
                "timestamp": "2021-12-17T08:02:00.000Z",
                "value": 6.156156156156102
            }
        ]
    }
]

Details about the body of the request can be found here: SummarizeMetricsDataDetails Reference. All the attributes and their description ca be found there.

Regarding the query, check the Monitoring Query Language (MQL) Reference page for details.

Test the Monitoring Queries

The Monitoring Queries can be tested using the OCI Console. Navigate to the Main Menu -> Observability & Management -> Metrics Explorer

Select the compartment, the Metric Namespace and make sure to check Advanced Mode to be able to write your own query:

Reference Documents

Ionut Adrian Vladu

I enjoy building python scripts for…everything! I am a Cloud enthusiast and I like to keep up with technology. When I'm not behind a computer, I like taking photos -- Visit My 500px profile -- or sit back and enjoy Formula 1 race weekends. Currently, working as a Tech Cloud Specialist @ Oracle
Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments