Creating a Query for a Custom Metric

Define a query for a custom metric in Monitoring.

For information about custom metrics, see Publishing Custom Metrics Using the API. For query troubleshooting, see Troubleshooting Queries.

  • These steps show how to create a query in Basic mode on the Metrics Explorer page. To create a query in Advanced mode (MQL), see Editing the MQL Expression for a Query.

    1. Create a basic query on the Metrics Explorer page.
    2. From the Console header, select the region that contains the metric data that you want.
      For more information about regions, see Understand Regions and Working Across Regions.
    3. In the query under the chart, select the compartment that contains the custom metric that you want.
    4. Select the metric namespace that contains the custom metric that you want.
      Example: mymetricsnamespace
    5. (Optional) Select the resource group that you want.
      Example: divisionX
    6. Select the name of the custom metric.
      Example: productOrder
    7. (Optional) Update the interval or statistic.
      Example: Select 1 minute for Interval, and select Sum for Statistic.
    8. To view and update the MQL expression, select Advanced mode.

      The MQL expression is in the Query code editor box. Example:

      productOrder[1m].sum()
    9. Select Update Chart.
      The chart shows data points for the custom metric, in a graph view. Example:Metric streams and values in a graph.
    10. (Optional) To switch to a table view, select Show Data Table.
      The chart shows data points for the custom metric, in a table view.
  • Use the oci monitoring metric-data summarize-metrics-data command and required parameters to query metric data.

    oci monitoring metric-data summarize-metrics-data --compartment-id <compartment_OCID> --namespace <metric_namespace> --query-text <mql_expression>

    The following example uses the --from-json parameter to retrieve custom metric information from a JSON file.

    oci monitoring metric-data summarize-metrics-data --from-json file://./get-metrics.json [...]

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

    Example JSON file for request

    Compare this file to the example of posted metric data at Publishing Custom Metrics Using the API.

    {
      "compartmentId": "$compartmentId",
      "endTime": "2023-01-08T20:00:00+00:00",
      "namespace": "mymetricsnamespace",
      "queryText": "productOrder[1m].sum()",
      "resolution": "5m",
      "resourceGroup": "divisionX",
      "startTime": "2023-01-07T23:00:00+00:00"
    }
    Example response

    This example response includes data points for the resource group division X only (ball product, NL country). Aggregation uses a one-minute interval, resulting in three timestamps.

    Compare this response to the example of posted metric data at Publishing Custom Metrics Using the API.

    {
      "data": [
        {
          "aggregated-datapoints": [
            {
              "timestamp": "2023-01-08T09:20:00+00:00",
              "value": 100.0
            },
            {
              "timestamp": "2023-01-08T10:15:00+00:00",
              "value": 110.0
            },
            {
              "timestamp": "2023-01-08T10:25:00+00:00",
              "value": 30.0
            },
          "compartmentId": "$compartmentId",
          "dimensions": {
            "country": "NL",
            "product": "ball"
          },
          "metadata": {
            "category": "toys",
            "note": "national holiday"
          },
          "name": "productOrder",
          "namespace": "mymetricsnamespace",
          "resourceGroup": "divisionX"
        }
      ]
    }
  • Run the SummarizeMetricsData operation to query metric data.