> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/improve/eng-intelligence/custom-metrics.md).

# Custom metrics

Engineering teams generate data everywhere—incidents resolved, coverage trends, deployment cadence, SLO drift—but most of it lives outside the tools that drive decisions. Custom metrics let you bring that data into Cortex, so the same analytics infrastructure you use for built-in engineering data can work with the metrics that matter most to your organization.

Whether you're pulling from an internal system, a tool Cortex doesn't natively integrate with, or computing derived values from existing integration data, custom metrics give you a consistent way to track, visualize, and act on that data. They surface in Data Explorer, on entity pages, and in Scorecards.

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

* **API** - Post custom metric data to Cortex via [the API](/api/readme/custom-metrics.md).
* **CQL** - Compute data based on a CQL query that is evaluated by Cortex every 12 hours.

## Use cases

Custom metrics are useful any time you have engineering data that lives outside Cortex's built-in integrations, or when you want to derive new meaning from data that's already there. Examples include:

* **Incident data from ServiceNow or other ITSM tools.** Track open incident counts, MTTR, or severity trends per service. Example CQL: `custom("servicenow-incidents").length`
* **Custom-computed SLO metrics.** If your SLO calculations live in an internal system or don't map cleanly to a native integration, push the computed values directly via API so they're visible alongside the rest of your engineering health data.
* **Metrics from homegrown tooling.** Internal platforms, custom CI pipelines, or proprietary monitoring tools can all post metric data to Cortex via API, making them first-class citizens in Eng Intelligence.
* **Derived metrics from existing integrations.** Combine or reframe data from tools Cortex already connects to, e.g. code coverage from Codecov (`codecov.codeCoverage()`) or quality metrics from SonarQube (`sonarqube.metric("coverage")`).

{% hint style="info" %}
When adding static or slowly changing metadata to entities, consider adding custom data instead of custom metrics. [Learn the differences](https://docs.cortex.io/improve/eng-intelligence/pages/0pawHMQrFlZ2APpwlqa3#custom-data-vs.-custom-metrics)
{% endhint %}

## Creating a custom metric and adding data

### Prerequisites

Users with the following permissions can configure custom metrics:

* `Configure Eng Intelligence Custom Metrics` - Allows for creation, editing, and deletion a custom metric definition. Editable fields include name, filter, and CQL expression. This permission also includes the ability to publish the custom metric.
* `Manage Eng Intelligence Custom Metric data` - Only required to manage custom metrics via the API. Grants access to the public API for adding and deleting data points on an API custom metric.

### Creating a custom metric via CQL

Follow the steps below to create a custom metric using CQL.

{% hint style="info" %}
Cortex evaluates CQL expressions every 12 hours to check for new metric data.
{% endhint %}

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the **Workspace** section, then expand **Eng Intelligence**.
4. Click **Custom metrics**.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/5eqcRxj8OpUn59LPTtDT" alt="Custom metrics option in the Settings sidebar." width="375"><figcaption></figcaption></figure></div>
5. In the upper-right corner, click **Add metric**.
6. In the **Custom metrics** side panel, select the **CQL** radio button.
7. Under **Name**, enter a name for the custom metric, e.g. `pager-volume-7d` (required).
8. Optionally, change the key. The key auto-populates based on the custom metric name and is made up of letters, digits, and hyphens.
9. Under **Description**, enter a description of the custom metric.
10. From the **Category** drop-down menu, assign the custom metric a category. This controls where the metric can be found for selection in Data Explorer.
11. Under **Trend color indicator**, set an indicator to match whether higher is better or worse. This controls the color-coding of trends in Data Explorer.
12. Under CQL query, click **Add CQL query**. In the side panel, add a CQL expression to evaluate every 12 hours. The result of the expression must be a number, otherwise validation fails. Click **Save query**. See [Cortex Query Language (CQL)](/standardize/cql.md) for more information.
13. From the **Entity types** drop-down menu, choose whether to include or exclude specific entity types.
14. Toggle off **Draft** when you’re ready to publish. 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 Data Explorer.
15. Click **Add metric**.

{% hint style="info" %}
The data retention period for custom metric data is 24 months.
{% endhint %}

{% hint style="info" %}
Results are not displayed until the end of the previous day.
{% endhint %}

### Creating a custom metric via API

Follow the steps below to create a custom metric using the API.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the **Workspace** section, then expand **Eng Intelligence**.
4. Click **Custom metrics**.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/5eqcRxj8OpUn59LPTtDT" alt="Custom metrics option in the Settings sidebar." width="375"><figcaption></figcaption></figure></div>
5. In the upper-right corner, click **Add metric**.
6. In the **Custom metrics** side panel, select the **API** radio button.
7. Under **Name**, enter a name for the custom metric, e.g. `pager-volume-7d` (required).
8. Optionally, change the key. The key auto-populates based on the custom metric name and is made up of letters, digits, and hyphens.
9. Under **Description**, enter a description of the custom metric.
10. From the **Category** drop-down menu, assign the custom metric a category. This controls where the metric can be found for selection in Data Explorer.
11. Under **Trend color indicator**, set an indicator to match whether higher is better or worse. This controls the color-coding of trends in Data Explorer.
12. Toggle off **Draft** when you’re ready to publish. 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 Data Explorer.
13. Click **Add metric**.

After defining the metric, you can post data to it via the [Cortex API](/api/readme/custom-metrics.md). Data points default to the current date and time, but results won't appear until the end of the previous day.

For information on adding metric data in bulk via the API, refer to [the documentation](/api/readme/custom-metrics.md). Note that bulk creation of metric data via the API is subject to rate limits and cardinality limits.

{% hint style="info" %}
The API supports backfilling custom metric data up to two (2) years.
{% endhint %}

## Editing a custom metric

When editing a custom metric, note that the `key` and `type` cannot be changed. To update either, archive the existing metric and recreate it with a new key. All other fields can be edited at any time.

Note that editing a CQL custom metric definition makes its historical values inaccessible.

**To edit a custom metric**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the **Workspace** section, then expand **Eng Intelligence**.
4. Click **Custom metrics**.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/5eqcRxj8OpUn59LPTtDT" alt="Custom metrics option in the Settings sidebar." width="375"><figcaption></figcaption></figure></div>
5. Locate the metric you want to edit, then click the **pencil icon** next to it.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/IXCJiXpYSYqI1tt3YTCo" alt="The pencil icon next to a custom metric." width="375"><figcaption></figcaption></figure></div>
6. Make any necessary changes, then click **Save metric**.

## Viewing custom metric data

Custom metric data is available in the following areas of Cortex:

* Data Explorer
* Entity details page
* All Metrics (Legacy View)

#### Viewing custom metric data in Data Explorer

From the main sidebar, expand **Eng Intelligence**, then select **Data Explorer**. Custom metrics appear in a list alongside other Eng Intelligence metrics.

#### Viewing custom metric data on an entity's details page

From an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details.md), click **Custom metrics** in the sidebar to view that entity's metrics.

<div align="left" data-with-frame="true"><figure><img src="/files/Pyf0VRFI22gffWnNBCIS" alt="Custom metrics option in the entity details sidebar." width="375"><figcaption></figcaption></figure></div>

#### Viewing custom metric data in All Metrics (Legacy View)

From the main sidebar, expand **Eng Intelligence**, then select **All Metrics**. Custom metrics appear in a list alongside other Eng Intelligence metrics.

<div align="left" data-with-frame="true"><figure><img src="/files/ecQY4A15OdgTWkdyvOEq" alt="Custom metrics displayed via the All Metrics tab." width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
[Customize your view](/improve/eng-intelligence/eng-intelligence.md#all-metrics-settings) by reordering or hiding the columns.
{% endhint %}