Custom Metrics

Overview

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.

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")

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.

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:

   • 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.

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

   • Ingestion method: Choose CQL.

   • CQL expression: Enter a CQL expression. The result of the expression must be a number, otherwise it will fail validation.

   • Publish immediately: Toggle this setting on to make this data immediately visible to all users with access to Eng Intelligence.

4. Click Add metric.

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

API

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:

   • 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.

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

   • Ingestion method: Choose API.

   • Publish immediately: Toggle this setting on to make this data immediately visible to all users with access to Eng Intelligence.

4. Click Save metric.

After defining the metric, you can post metric data to it via the Cortex API.

Bulk-add metric data via API

Bulk-add multiple metric points to an entity using createBulkCustomMetricData.

When using the API, it is possible to backfill custom metric data up to two years.

Note that bulk creation of metric data via the API is subject to rate limits and cardinality limits.

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.

Viewing custom metrics

View custom metric definitions

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

View custom metric data

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

View custom metric data on an entity page

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

Customize the appearance of custom metrics

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

1. In Cortex, navigate to the Eng Intelligence 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.