Publishing Custom Metrics Using the API
Publish custom metrics to the Monitoring service.
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_ororacle_). - 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.
Metric-Posting Clients
For information about developing a metric-posting client, see Developer Guide. For an example client, see MonitoringMetricPostExample.java.
For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.
This task can't be performed in the Console. - Note
Unlike other Monitoring commands that usetelemetryendpoints, this command requires atelemetry-ingestionendpoint.Use the oci monitoring metric-data post command, the
--endpointparameter, and required parameters to publish custom metrics:oci monitoring metric-data post --metric-data file://<json_file_path> --endpoint https://telemetry-ingestion.<region>.oraclecloud.comFor a complete list of parameters and values for CLI commands, see the Command Line Reference for Monitoring.
Example JSON file for requestThe 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 } } - Metric namespace:
- Note
Unlike other Monitoring operations that usetelemetryendpoints, this operation requires atelemetry-ingestionendpoint.Run the PostMetricData operation to publish custom metrics.
Example of a batched requestThis 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 } ] } ]
More Information
To walk through common use cases with custom metrics, see Custom Metrics Walkthrough. For query troubleshooting, see Troubleshooting Queries.