Custom Metrics

Define your own custom time series metrics to power the analytics in your Eng Intelligence dashboard, drawing from your integrations with Cortex or your organization's internal data. In addition to seeing these in Eng Intelligence, you’ll also be able to view these in the entity pages and use them in Scorecards.

After defining a custom metric, the metric data can be provided via the following methods:

• API: Post custom metric data to Cortex via the API.

• CQL: Compute data based on a CQL query that is evaluated by Cortex every 12 hours.

Support for custom metrics in the new Metrics Explorer and Custom Dashboards (Public Beta) experiences is in beta for all cloud customers. Support for on-prem is coming soon. Please reach out to Cortex Customer Engineering with any feedback.

Use cases

Some examples of custom metrics you might want to surface in Eng Intelligence include:

• ServiceNow incident data

  • Example CQL: custom("servicenow-incidents").length

• Custom-computed SLO metrics

• Homegrown tools that generate metrics through custom data

• Code coverage or vulnerability metrics from existing integrations

  • Example CQL: codecov.codeCoverage() or sonarqube.metric("coverage")

If you are adding static or slowly changing metadata to entities, consider adding custom data instead of custom metrics. Learn more about the differences in Adding custom data.

Managing custom metrics

Prerequisites

Before configuring custom metrics, your user must have the following permissions set in Cortex:

• Configure Eng Intelligence Custom Metrics

  • This permission allows you to create, edit, and delete a custom metric definition. The fields that can be edited are the name, filter, CQL expression. This permission also includes the ability to publish the custom metric.

• Manage Eng Intelligence Custom Metric data

  • This permission is only required if you are managing custom metrics via the API. It allows you to hit the public API to add and delete data points for an API Custom Metric.

Define custom metrics and add metric data

See the tabs below for instructions on creating custom metrics with CQL or via the API.

The data retention period for custom metric data is 24 months.

When custom metric data points are added, Cortex lags results until the end of the previous day.

CQL

1. In Cortex, navigate to the Eng Intelligence custom metrics settings.

2. In the upper right side of the list of custom metrics, click Add metric.

3. Fill in the "Add metric" form:

   • Ingestion method: Choose CQL.

   • Name: Enter the name of the custom metric that will appear in Eng Intelligence.

   • Key: Enter a unique identifier for the custom metric made up of letters, digits, and hyphens, e.g., my-custom-metric.

   • Description: Add a description for the custom metric.

   • Category: Choose the category for the metric. This controls where the metric can be found for selection in Metrics Explorer.

   • Trend color indicator: Choose whether an upward or downward trend is green. This controls the color-coding of trends in Metrics Explorer.

   • CQL query: Add a CQL expression to evaluate every 12 hours. The result of the expression must be a number, otherwise it will fail validation.

   • Entity types: Choose whether to include or exclude specific entity types.

   • Draft: By default, the custom metric is in draft state and only visible to users with the permission to configure custom metrics. Toggle this setting off to immediately enable the metric within All Metrics and Metrics Explorer.

4. Click Add metric.

Cortex will evaluate the CQL expression every 12 hours to check for new metric data.

API

Edit custom metric definition

Note that you cannot update the key or the type, but you can edit the name, entity type filter, CQL expression, and whether the metric is published. If you need to change the key or the type, you will need to archive the current metric and re-create it with a new key.

If you edit a CQL custom metric definition, the older values of the metric will no longer be accessible.

To edit a custom metric:

1. In Cortex, navigate to the Eng Intelligence custom metrics settings.

2. In the list of metrics, locate the one you want to edit. Click the pen icon on the right side of the metric.

3. Make any necessary changes, then click Save metric.

In Cortex, navigate to the Eng Intelligence custom metrics settings.

Viewing custom metric data

View custom metric data in Metrics Explorer

Support for custom metrics in the new Metrics Explorer and Custom Dashboards (Public Beta) experiences is in beta for all cloud customers. On-prem support is coming soon. Please reach out to Cortex Customer Engineering with any feedback.

From the main nav of Cortex, click Eng Intelligence > Metrics Explorer. The custom metrics will appear alongside the other Eng Intelligence metrics in the Metrics Explorer.

View custom metric data on an entity page

While viewing an entity details page, click Custom metrics from the sidebar to view metrics for that entity:

View custom metric data in All Metrics (Legacy View)

From the main nav of Cortex, click Eng Intelligence > All Metrics. The custom metrics will appear alongside the other Eng Intelligence metrics in the table.

When custom metric data points are added, Cortex lags results until the end of the previous day.

You can customize your view by reordering the columns or hiding columns.

1. In Cortex, navigate to the All Metrics appearance settings.

   • Rearrange columns: In the list of metrics, click and drag each tile into your preferred order.

   • Hide a column: Click the trash icon on the right side of a metric tile.

     • To add a column back into the view, select it from the Columns drop-down. In the dropdown, the columns with a checkmark have been added already. The columns without a checkmark have been hidden.

2. When you are done reordering or hiding columns, click Save changes at the bottom of the page.