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

Create metrics with CQL

1. In Cortex, navigate to the Eng Intelligence settings:
   1. Click your avatar in the lower left corner, then click Settings.
   2. Under "Workspace," click Eng Intelligence.
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 Save metric.

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

API

Create metrics via API

1. In Cortex, navigate to the Eng Intelligence settings:
   1. Click your avatar in the lower left corner, then click Settings.
   2. Under "Workspace," click Eng Intelligence.
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, click your avatar in the lower left corner, then click Settings.
2. Under "Workspace" settings, click Eng Intelligence.
3. In the list of metrics, locate the one you want to edit. Click the pen icon on the right side of the metric.
   
4. Make any necessary changes, then click Save metric.

Viewing custom metrics

View custom metric definitions

1. In Cortex, click your avatar in the lower left corner, then click Settings.
2. Under "Workspace" settings, click Eng Intelligence.

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, click your avatar in the lower left corner, then click Settings.
2. Under "Workspace" settings, click Appearance.
3. At the top of the Appearance page, click the "Eng Intelligence" tab.
   • 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.
     • As you hide columns, they move into a drop-down list at the bottom of this page. To add a column back into the view, select it from the drop-down and click Add.
       
4. When you are done reordering or hiding columns, click Save at the bottom of the page.