Oracle Cloud Infrastructure Documentation

Publishing Custom Metrics Using the API

Publish custom metrics to the Monitoring service.

Tip

Agent configurations are another way to publish custom metrics to Monitoring. With agent configurations, the API isn't necessarily required to publish custom metrics. You can now use agent configurations to ingest metric data into custom metrics. For example, expose metrics from a virtual machine (VM) using an HTTP endpoint in Prometheus format.

A custom metric is a metric that you design to collect and analyze data.

For example, create a productOrder metric (in a metric namespace, mymetricsnamespace) to track product orders by country and division, with additional metadata for product categories and notes.

Before You Begin

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 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 the administrator. You might not have the required type of access in the current compartment .

Administrators: For an example policy, see Publish Custom Metrics (Securing Monitoring).

Considerations

When defining custom metrics, note the following:

  • For the metric namespace, don't use a reserved prefix (oci_ or oracle_).
  • Ensure that custom metrics don't exceed limits. For example, note the valid range of dimensions and maximum number of streams for custom metrics. See PostMetricData.
  • Define 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 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. See also Limits on Monitoring.
  • Ensure that timestamp values are near current time. For a data point to be posted, its timestamp must be near current time (less than two hours in the past and less than 10 minutes in the future). See PostMetricData.
  • After publishing custom metrics, you can access them the same way you access any other metrics stored by the Monitoring service: View charts in the Console, query metrics using the CLI or API, and create alarms.
  • When retrieving custom metrics, you can match to a resource group. Blank (null) for resource group returns metric data that doesn't have a resource group.
  • This task can't be performed in the Console.
  • Note

    Unlike other Monitoring commands that use telemetry endpoints, this command requires a telemetry-ingestion endpoint.

    Use the oci monitoring metric-data post command, the --endpoint parameter, and required parameters to publish custom metrics:

    oci monitoring metric-data post --metric-data <json_file_path> --endpoint https://telemetry-ingestion.<region>.oraclecloud.com

    For a complete list of parameters and values for CLI commands, see the Command Line Reference for Monitoring.

    Example JSON file for request

    The example JSON file includes the following items.

    • Metric namespace: mymetricsnamespace
    • Metric name: productOrder
    • Product dimension
    • Country dimension
    • Resource group (DivisionX, DivisionY)
    • Additional metadata for category and note
    [
  {
    "compartmentId": "$compartmentId",
    "datapoints": [
      {
        "count": 10,
        "timestamp": "2023-01-08T04:18:01+00:00",
        "value": 5.0
      },
      {
        "count": 3,
        "timestamp": "2023-01-08T05:11:01+00:00",
        "value": 10.0
      }
    ],
    "dimensions": {
      "product": "ball",
      "country": "NL"
    },
    "metadata": {
      "category": "toys",
      "note": "national holiday"
    },
    "name": "productOrder",
    "namespace": "mymetricsnamespace",
    "resourceGroup": "divisionX"
  },
  {
    "compartmentId": "$compartmentId",
    "datapoints": [
      {
        "count": 7,
        "timestamp": "2023-01-08T03:22:01+00:00",
        "value": 3.0
      },
      {
        "count": 11,
        "timestamp": "2023-01-08T05:08:03+00:00",
        "value": 2
      }
    ],
    "dimensions": {
      "product": "The Road to Nowhere",
      "country": "FR"
    },
    "metadata": {
      "category": "books",
      "note": "start second semester"
    },
    "name": "productOrder",
    "namespace": "mymetricsnamespace",
    "resourceGroup": "divisionY"
  }
]
    Example response
    {
  "data": {
    "failed-metrics": [],
    "failed-metrics-count": 0
  }
}
  • Note

    Unlike other Monitoring operations that use telemetry endpoints, this operation requires a telemetry-ingestion endpoint.

    Run the PostMetricData operation to publish custom metrics.

    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":"2023-01-10T22:19:20Z",
            "value":83.0
         },
         {
            "timestamp":"2023-01-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":"2023-01-10T22:19:10Z",
            "value":100.0
         },
         {
            "timestamp":"2023-01-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":"2023-01-10T22:19:00Z",
            "value":87.0,
            "count":60
         },
         {
            "timestamp":"2023-01-10T22:19:00Z",
            "value":96.0,
            "count":30
         }
      ]
   }
]