> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getunleash.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getunleash.io/_mcp/server.

# Impact metrics

> Impact metrics connect application data to your feature flags and release plans. Use internal metrics from the SDK or external metrics from Prometheus and VictoriaMetrics.

## Overview

Impact metrics connect application data, such as request counts, error rates, or memory usage, to your feature flags and release plans.

You can use impact metrics in two areas:

* **[Charts](#create-charts)**: Visualize data in the Impact Metrics section of the Admin UI.
* **[Release management](#automate-release-progression)**: Automate milestone progression or trigger [safeguards](#configure-safeguards) that pause rollouts or disable environments when metrics cross a threshold.

By combining impact metrics with [release templates](/concepts/release-templates), you can automate milestone progression and react automatically when metrics cross defined thresholds. For example:

* Progress from 25% to 50% only if error rates stay below a threshold.
* Pause automatically when request latency increases during a rollout.
* Disable the environment if error counts spike past a critical level.

![Example of impact metrics displaying](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/unleash.docs.buildwithfern.com/998d241a8a938ab3b3c74d413a82e911a50fb155adebecdfb240013167e26c3a/assets/impact-metrics.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260808%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260808T104501Z&X-Amz-Expires=604800&X-Amz-Signature=770469d0115c56f175f65666c6f1b4b9791af9b7a46d22ddf58ab8df374866c1&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

For more use cases and how impact metrics fit into the broader release workflow, see [Release management overview](/concepts/release-management-overview).

## Metric sources

Unleash supports two metric sources: [internal](#internal-metrics) and [external](#external-metrics). Both support the same [metric types](#metric-types) and can be used in [charts](#create-charts) and [safeguards](#configure-safeguards).

### Internal metrics

Internal metrics are defined and recorded in your application using an [Unleash SDK](/sdks#metrics-and-impression-data). The SDK sends metrics to Unleash, where they are stored and queried. See [Record internal metrics](#record-internal-metrics) for setup instructions.

### External metrics

External metrics are queried at read time from your existing [Prometheus](https://prometheus.io/) or [VictoriaMetrics](https://victoriametrics.com/) instance. The data stays in your system. Unleash does not ingest or store it. See [Connect external metrics](#connect-external-metrics) for setup instructions.

### Source isolation

Internal and external metrics are completely separate in Unleash. Each chart or safeguard is configured against a specific source, and the metric selector labels entries by their source. A metric with the same name can exist in both sources without conflict.

If the external instance is unreachable or returns errors, only charts and safeguards configured against the [external](#external-metrics) source are affected. [Internal metrics](#internal-metrics) continue to work normally.

## Metric types

Impact metrics support three data types:

* **Counters**: Cumulative values that only increase, such as request counts, error counts, or event totals.
* **Gauges**: Values that fluctuate up or down, such as memory usage or the number of active users.
* **Histograms**: Distributions of values, such as request duration or response size. Unleash calculates percentiles (p50, p95, p99).

## Record internal metrics

[Internal metrics](#internal-metrics) are currently supported in a [select number of SDKs](/sdks#metrics-and-impression-data). To request support for additional SDKs, contact [beta@getunleash.io](mailto:beta@getunleash.io).

To use [internal metrics](#internal-metrics), define a metric in the SDK and then record values for it. The SDK automatically attaches the following context labels: `appName`, `environment`, and `origin` (for example, `origin=sdk` or `origin=Edge`). These labels are available as filters when you [create charts](#create-charts).

#### Counters

```javascript
// 1. Define the counter
unleash.impactMetrics.defineCounter(
  'request_count',
  'Total number of HTTP requests processed'
);

// 2. Increment the counter
unleash.impactMetrics.incrementCounter('request_count');
```

#### Gauges

```javascript
// 1. Define the gauge
unleash.impactMetrics.defineGauge(
  'heap_memory_total',
  'Current heap memory usage in bytes'
);

// 2. Update the gauge value
const currentHeap = process.memoryUsage().heapUsed;
unleash.impactMetrics.updateGauge('heap_memory_total', currentHeap);
```

#### Histograms

```javascript
// 1. Define the histogram
unleash.impactMetrics.defineHistogram(
  'request_time_ms',
  'Time taken to process a request in milliseconds'
);

// 2. Record a value
const duration = 125;
unleash.impactMetrics.observeHistogram('request_time_ms', duration);
```

For language-specific examples, refer to your [SDK documentation](/sdks#metrics-and-impression-data).

### Create a metric from the UI

You can also define an [internal metric](#internal-metrics) directly in the Admin UI, without writing the definition in code first. On the feature flag page, click **Add impact metric** in the impact metric banner. In **Metric name**, search for the metric you want to track; if it doesn't exist yet, click **Set up your first metric** to define it.

Creating a metric in the UI only defines it. To record values for the metric, instrument your application with an [Unleash SDK](/sdks#metrics-and-impression-data) as described in [Record internal metrics](#record-internal-metrics).

### Ingestion and batching

[Internal metrics](#internal-metrics) are batched and sent on the same interval as [regular SDK metrics](/concepts/impression-data). They are ingested through the regular metrics endpoint.

### Unleash Edge behavior

Unleash Edge forwards [internal metrics](#internal-metrics) received from SDKs to the Unleash API. The origin label appears as `origin=Edge`. Daisy-chaining Edge instances is not supported.

If an Edge instance accumulates a large batch of metrics due to a temporary network disconnect, it sends them as a single bulk request upon reconnection. This appears as a spike in your counter graphs rather than a smooth distribution over time. This is expected behavior.

## Connect external metrics

If you already collect metrics in Prometheus or VictoriaMetrics, you can connect your instance to Unleash and use those metrics in [charts](#create-charts) and [safeguards](#configure-safeguards) without re-instrumenting your application through the SDK.

[External metrics](#external-metrics) are not stored in Unleash. Unleash queries your instance at read time when a chart is viewed or a safeguard is evaluated.

### Enable external metrics

You can configure external metrics from the Admin UI on both [Unleash Hosted](/deploy/hosting-options) and self-hosted instances.

1. In the Admin UI, go to **Admin settings > Impact Metrics**.
2. Toggle **Enable external metrics** to **Enabled**.
3. In **Metrics source URL**, enter the base URL of your Prometheus or VictoriaMetrics instance.
4. Click **Test integration** to verify that Unleash can reach the endpoint.
5. Click **Save**.

Unleash appends the standard Prometheus HTTP API paths (`/api/v1/...`) to this base URL, so do not include `/api/v1` yourself. A trailing slash is accepted and ignored. Examples:

* Plain Prometheus: `https://prometheus.example.com`
* VictoriaMetrics cluster or multi-tenant: `https://victoria.example.com/select/<tenantId>/prometheus`

The URL must be reachable from the Unleash server over the network. Each request has a 20-second timeout.

HTTP Basic Auth is supported by embedding credentials in the URL (for example, `https://user:password@prometheus.example.com`). Credentials in URLs can appear in server logs. Use a secrets manager or other secure mechanism if you provision the URL through configuration rather than the Admin UI.

#### Configure with an environment variable

If you prefer to manage configuration outside the Admin UI on a self-hosted instance, set the `EXTERNAL_PROMETHEUS_IMPACT_METRICS_API` environment variable on your Unleash server to the base URL of your Prometheus or VictoriaMetrics instance. Unleash must be restarted for changes to take effect.

### Metric selector filtering

Prometheus and VictoriaMetrics typically expose many infrastructure metrics that are not relevant as impact metrics. Unleash filters these out of the metric selector.

#### Excluded metrics

Unleash excludes the reserved names `up`, `ALERTS`, and `ALERTS_FOR_STATE`, and any metric whose name starts with a well-known infrastructure prefix: `go_`, `process_`, `prometheus_`, `promhttp_`, `scrape_`, `vm_`, `vmagent_`, `vminsert_`, `vmselect_`, `container_`, `kube_`, or similar tooling prefixes. If one of your own metrics collides with an excluded prefix, rename it to make it visible.

#### Excluded labels

Unleash hides Prometheus reserved labels (those starting with `__`) and common infrastructure labels such as `instance`, `job`, `namespace`, `pod`, `container`, `node`, and `app_kubernetes_io_*`. All other labels are exposed as filter options, up to 10 per metric.

## Create charts

You can visualize both [internal](#internal-metrics) and [external](#external-metrics) metrics in the Unleash Admin UI.

1. Go to **Impact Metrics** in the sidebar.
2. Click **New Chart**.
3. In the **Add New Chart** dialog, configure the following:
   * Data series: Select a metric. The selector labels each metric with its source ([internal](#internal-metrics) or [external](#external-metrics)).
   * Time: Select a window (for example, Last 24 hours).
   * Mode (aggregation type): Choose how to display the data.
     * For counters: Rate per second, Count
     * For gauges: Sum, Average
     * For histograms: p50, p95, p99
   * Filters: For [internal metrics](#internal-metrics), filter by `appName`, `environment`, or `origin`. For [external metrics](#external-metrics), filter by any custom labels exposed by your Prometheus or VictoriaMetrics instance.
4. Click **Add chart**.

![Creating a new impact metrics chart in the Admin UI](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/unleash.docs.buildwithfern.com/44f308dd33c006540025248b3c85c3ddb49caf248854e4d9aab0dfb9d9c577cc/assets/add-new-impact-metrics-chart.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260808%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260808T104501Z&X-Amz-Expires=604800&X-Amz-Signature=402fa00021f3517e8f8cdfac679f29d7c286a5f4466562becaf8dad1231c6fcc&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

There is a 1-2 minute delay between data generation and visualization for [internal metrics](#internal-metrics) due to the ingestion cycle. [External metrics](#external-metrics) reflect whatever data is currently available in your Prometheus or VictoriaMetrics instance.

## Automate release progression

Impact metrics integrate with [release templates](/concepts/release-templates) to automate the rollout process. Instead of manually advancing milestones, Unleash can progress automatically when time conditions are met.

To configure automatic progression:

1. Open a feature flag that [uses a release template](/concepts/release-templates#apply-a-release-template-to-a-feature-flag).
2. Select a milestone and click **Add automation**.
3. Define the conditions:
   * Time: The minimum duration the milestone must run. For example, proceed after 24 hours.
4. Click **Save**.

When the time conditions are satisfied, Unleash advances the release to the next milestone.

## Configure safeguards

Safeguards automatically react when an impact metric crosses a threshold. You can configure safeguards against both [internal](#internal-metrics) and [external](#external-metrics) metrics.

Safeguards are attached to a feature flag's environment, so you can react differently in development, staging, and production using the same metric.

### Safeguard actions

When you add a safeguard, you choose an action that runs if the metric crosses the threshold:

* **Disable environment**: Turns the flag off in this environment in Unleash. Connected SDKs and the Frontend API pick up the change on their next refresh interval, so it is not an instant client-side cut-off.
* **Pause release plan automation**: Stops automatic milestone progression. The current milestone keeps serving traffic, and you can investigate before manually resuming. This action only applies if the flag has an active release plan in the environment.

### Add a safeguard

Before you start, verify that your metric is available by selecting **Add safeguard** and checking the dropdown. For [internal metrics](#internal-metrics), it may take up to 60 seconds for a new metric to appear because the SDK sends metrics on a default 60-second interval.

To add a safeguard to an environment:

1. Open the feature flag and locate the environment you want to protect.
2. Click **Add safeguard** and select the action: **Disable environment** or **Pause release plan automation**.
3. Select your impact metric from the dropdown. The selector labels each metric with its source.
4. Configure the threshold. For example:
   * Metric: `analyze_feature_error`
   * Aggregated by: Count
   * Condition: More than 10 in the last 15 minutes
5. Click **Save**.

When the metric crosses the threshold, Unleash runs the configured action for that environment.

### External metrics safeguard behavior

Safeguards work the same way for both [internal](#internal-metrics) and [external](#external-metrics) metrics, with the following differences for external metrics:

* **Environment scoping**: To scope an external metric to a specific Unleash environment, add an `environment` label to the metric whose value matches the environment name (for example, `environment="production"`). The safeguard then only evaluates time series with that label. If the `environment` label is missing, the metric is available in every environment with no per-environment filtering.
* **No custom-label filtering**: Safeguards against [external metrics](#external-metrics) evaluate the metric across all time series. You cannot filter by custom labels. If you need a narrower scope, expose a dedicated metric in your Prometheus or VictoriaMetrics instance with the scope already applied.
* **Missing configuration**: If the external URL is not configured (for example, the environment variable is unset), safeguards configured against the [external](#external-metrics) source are skipped rather than failing the release. Reconfiguring the URL restores them.

## Load on your external metrics backend

Connecting an external instance adds read load to your Prometheus or VictoriaMetrics, similar to Grafana or other query-time tools. Plan capacity accordingly as the number of charts and active safeguards grows.

Unleash issues the following Prometheus HTTP API requests:

| Endpoint                                                  | Purpose                                                      |
| --------------------------------------------------------- | ------------------------------------------------------------ |
| `GET /api/v1/label/__name__/values`                       | Lists available metric names in the selector                 |
| `GET /api/v1/labels` and `GET /api/v1/label/:name/values` | Populates label filters in the UI                            |
| `GET /api/v1/query_range`                                 | Renders chart time series and evaluates safeguard thresholds |

Metadata requests run when you open the chart or safeguard configuration UI. Range queries run when charts are viewed and each time a safeguard is evaluated.