# Custom Metrics

Define your own custom time series metrics to power the analytics in Eng Intelligence Metrics Explorer and Custom Dashboards, 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](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/custom-metrics).
* **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")`

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](https://docs.cortex.io/ingesting-data-into-cortex/entities/custom-data#custom-data-vs.-custom-metrics).

## Managing custom metrics

### Prerequisites

Before configuring custom metrics, your user must have the following [permissions](https://docs.cortex.io/configure/settings/managing-users/permissioning) 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.

{% hint style="info" %}
When custom metric data points are added, Cortex lags results until the end of the previous day.
{% endhint %}

{% tabs %}
{% tab title="CQL" %}

1. In Cortex, navigate to the [Eng Intelligence custom metrics settings](https://app.getcortexapp.com/admin/settings/eng-intelligence/custom-metrics).
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.
{% endtab %}

{% tab title="API" %}

1. In Cortex, navigate to the [Eng Intelligence custom metrics settings](https://app.getcortexapp.com/admin/settings/eng-intelligence/custom-metrics).
2. In the upper right side of the list of custom metrics, click **Add metric**. ![In the upper right, click Add Metric](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-1342666fc6902f1537c97cd237feb189d69aa76d%2Fadd-custom-metric.jpg?alt=media)
3. Fill in the "Add metric" form:
   * **Ingestion method**: Choose **API**.
   * **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.
   * **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 **Save metric**.

After defining the metric, you can post metric data to it via the [Cortex API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/custom-metrics). The API endpoints for adding custom metric data points default to the current day's date and time, but note that Cortex will not display metrics until the end of the previous day.

**Bulk-add metric data via API**

[Bulk-add multiple metric points to an entity using the API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/custom-metrics).

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.
{% endtab %}
{% endtabs %}

### 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](https://app.getcortexapp.com/admin/settings/eng-intelligence/custom-metrics).
2. In the list of metrics, locate the one you want to edit. Click the pen icon on the right side of the metric.\ <img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-b99977926bd9ad789ea1ce4ec6ad421abd8f7f2d%2Fedit-custom-metric.jpg?alt=media" alt="Click the pen icon to edit a custom metric" data-size="original">
3. Make any necessary changes, then click **Save metric**.

In Cortex, navigate to the [Eng Intelligence custom metrics settings](https://app.getcortexapp.com/admin/settings/eng-intelligence/general?activeTab=custom-metrics).

## Viewing custom metric data

#### View custom metric data in Metrics Explorer

From the main nav of Cortex, click **Eng Intelligence > Metrics Explorer.** The custom metrics will appear for selection alongside other Eng Intelligence metrics in the [metrics-explorer](https://docs.cortex.io/improve/eng-intelligence/metrics-explorer "mention").

#### View custom metric data on an entity page

While viewing an [entity details page](https://docs.cortex.io/ingesting-data-into-cortex/entities/details), click **Custom metrics** from the sidebar to view metrics for that entity:\
![Click "Custom metrics" on the left side of an entity page](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-f3c8e30d01bad0740b29d8a8bd246a682d1d7701%2Fcustom-metric-entity.jpg?alt=media)

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

You can customize your view by reordering the columns or hiding columns in the [All Metrics appearance settings](https://app.getcortexapp.com/admin/settings/eng-intelligence/general) page.