Publishing Custom Metrics

This topic describes how to publish your own custom metrics  to the Monitoring service.

You can publish your own metrics to Monitoring using the API. You can view charts of your published metrics using the Console , query metrics using the API, and set up alarms  using the Console or API.

Caution

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: To publish custom metrics, you must be given the required type of access in a policy  written by an administrator. This requirement applies whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, check with your administrator. You may not have the required type of access in the current compartment . Administrators: For a related common policy, see Let users publish custom metrics.

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.

Note

When defining your custom metrics, note the following:

  • Ensure that your custom metrics do not exceed limits. For example, note the valid range of dimensions and maximum number of streams for custom metrics. See PostMetricData.
  • Define your metrics with aggregation in mind. While custom metrics can be posted as frequently as every second (minimum frequency of one second), the minimum aggregation interval is one minute.
  • Define your metrics with return limits in mind. Limits information for returned data includes the 100,000 data point maximum and time range maximums (determined by resolution, which relates to interval). See MetricData Reference.
  • When retrieving custom metrics, you can match to a resource group. Blank (null) for resource group returns metric data that does not have a resource group.

Use this API operation to publish custom metrics: 

PostMetricData

Note

Oracle recommends the following: 

  • Send batched requests to maximize metric streams per request. A batched request contains multiple metrics or metric namespaces. Note limits. See PostMetricData.
  • Publish metrics only when relevant contexts require monitoring; that is, when data points need to be collected. If you want to publish metrics during inactive periods when no observations exist, then you can manually create "0" values for publishing.

You can access your published custom metrics the same way you access any other metrics stored by the Monitoring service. View charts from queries using the Console, query metrics using the CLI or API, and set up alarms using the Console, CLI, or API.

Example of a batched request

This example shows a single request containing data points  for metrics across two metric namespaces .

[
   {
      "namespace":"myFirstNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "resourceGroup":"myFirstResourceGroup",
      "name":"successRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.exampleuniqueID",
         "appName":"myAppA"
      },
      "metadata":{
         "unit":"percent",
         "displayName":"MyAppA Success Rate"
      },
      "datapoints":[
         {
            "timestamp":"2019-03-10T22:19:20Z",
            "value":83.0
         },
         {
            "timestamp":"2019-03-10T22:19:40Z",
            "value":90.1
         }
      ]
   },
   {
      "namespace":"myFirstNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "resourceGroup":"mySecondResourceGroup",
      "name":"successRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.differentuniqId",
         "appName":"myAppA"
      },
      "metadata":{
         "unit":"percent",
         "displayName":"MyAppA Success Rate"
      },
      "datapoints":[
         {
            "timestamp":"2019-03-10T22:19:10Z",
            "value":100.0
         },
         {
            "timestamp":"2019-03-10T22:19:30Z",
            "value":100.0
         }
      ]
   },
   {
      "namespace":"mySecondNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "name":"deliveryRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.exampleuniqueID",
         "appName":"myAppB"
      },
      "metadata":{
         "unit":"bytes",
         "displayName":"MyAppB Delivery Rate"
      },
      "datapoints":[
         {
            "timestamp":"2019-03-10T22:19:00Z",
            "value":87.0,
            "count":60
         },
         {
            "timestamp":"2019-03-10T22:19:00Z",
            "value":96.0,
            "count":30
         }
      ]
   }
]