> ## Documentation Index
> Fetch the complete documentation index at: https://tyk.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Metrics Configuration in Tyk Gateway

> Learn how to configure Tyk Gateway to export metrics using OpenTelemetry Protocol (OTLP) and legacy approaches.

## Introduction

Metrics provide aggregated, quantitative data about the performance and behavior of your APIs over time. They offer insights into the overall health of the system.

Tyk supports several ways to export metrics, from different components:

| Method                                                  | Component                    | Status                                                                                     | Description                                                                                            |
| ------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| [OpenTelemetry Metrics](#opentelemetry-metrics)         | Tyk Gateway                  | **Recommended**                                                                            | Native OTLP metrics export. Works with any OpenTelemetry-compatible backend.                           |
| [Metrics Pumps](#metrics-pumps)                         | Tyk Pump                     | Legacy                                                                                     | Prometheus, StatsD, or DogStatsD metrics derived from traffic logs. Relevant for existing deployments. |
| [New Relic Instrumentation](#new-relic-instrumentation) | Tyk Gateway                  | [Deprecated](/docs/developer-support/deprecation#understanding-deprecation-and-end-of-life-eol) | Legacy New Relic agent integration available since Gateway v2.5.                                       |
| [StatsD Instrumentation](#statsd-instrumentation)       | Tyk Gateway, Pump, Dashboard | [Deprecated](/docs/developer-support/deprecation#understanding-deprecation-and-end-of-life-eol) | Legacy StatsD protocol export for Gateway, Pump, and Dashboard.                                        |

## OpenTelemetry Metrics

### Availability

| Component   | Version                                                                                  | Edition                |
| :---------- | :--------------------------------------------------------------------------------------- | :--------------------- |
| Tyk Gateway | Available since [v5.13.0](/docs/developer-support/release-notes/gateway#5-13-0-release-notes) | Community & Enterprise |

### Tyk Gateway Metrics

Tyk Gateway natively exports metrics via the OpenTelemetry Protocol (OTLP), the recommended way to collect Gateway metrics. When enabled, the Gateway pushes standard RED metrics (Rate, Errors, Duration) plus Go runtime and configuration state metrics to any OTLP-compatible backend. Some backends accept this natively; others need an OpenTelemetry Collector in between, see [Supported Backends](#supported-backends) below.

For a complete reference, see:

* [Default Metrics](/docs/api-management/metrics/default-metrics): all metrics exported automatically (RED, Go runtime, configuration state)
* [Custom Metrics](/docs/api-management/metrics/custom-metrics): defining custom counters and histograms with your own dimensions

### Supported Backends

The metrics exporter sends data using standard OTLP, so any OTLP-compatible backend works. Some common setups:

**Via OTel Collector (recommended for self-managed):** Route metrics from the OTel Collector to Prometheus, Grafana Mimir, Splunk, or other backends. The Collector also handles batching, retries, and fanout to multiple destinations.

**Direct OTLP:** Send directly to backends that natively accept OTLP, such as:

* New Relic (`otlp.nr-data.net:4317`)
* Dynatrace (via the Dynatrace OTLP endpoint)
* Grafana Cloud Mimir

Standalone Prometheus doesn't accept OTLP by default: use the OTel Collector path above, unless you're running Prometheus v3.0+ with its native OTLP receiver explicitly enabled.

## Configuration Options

Metrics can be enabled independently; distributed tracing does not need to be configured. To configure distributed tracing alongside metrics, see [Distributed Tracing](/docs/api-management/traces).

### Enable Metrics

If you only need metrics export, configure the `metrics` sub-object directly:

```json theme={null}
{
  "opentelemetry": {
    "metrics": {
      "enabled": true,
      "endpoint": "otel-collector:4317"
    }
  }
}
```

### Traces and metrics together

When both are configured, `metrics.endpoint` defaults to the `traces.endpoint` value if not set explicitly:

```json theme={null}
{
  "opentelemetry": {
    "traces": {
      "enabled": true,
      "endpoint": "otel-collector:4317"
    },
    "metrics": {
      "enabled": true
    }
  }
}
```

This is enough to start exporting [default Gateway metrics](/docs/api-management/metrics/default-metrics) to the same OTLP endpoint configured for traces.

### Reference

| Field                                                                                                                | Description                                                                                        | Default |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------- |
| [opentelemetry.metrics.enabled](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-enabled)                        | Enable OTLP metrics export                                                                         | `false` |
| [opentelemetry.metrics.exporter](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-exporter)                      | Export protocol: `grpc` or `http`                                                                  | `grpc`  |
| [opentelemetry.metrics.endpoint](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-endpoint)                      | OTLP collector endpoint. Defaults to `opentelemetry.traces.endpoint` if not set                    | —       |
| [opentelemetry.metrics.connection\_timeout](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-connection_timeout) | Connection timeout in seconds                                                                      | `1`     |
| [opentelemetry.metrics.headers](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-headers)                        | Additional HTTP headers sent with each OTLP export request                                         | —       |
| [opentelemetry.metrics.tls](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-tls)                                | TLS configuration for the OTLP connection                                                          | —       |
| [opentelemetry.metrics.export\_interval](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-export_interval)       | How often metrics are pushed to the backend, in seconds                                            | `60`    |
| [opentelemetry.metrics.shutdown\_timeout](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-shutdown_timeout)     | Maximum time allowed for a single export request, in seconds                                       | `30`    |
| [opentelemetry.metrics.cardinality\_limit](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-cardinality_limit)   | Maximum unique attribute combinations tracked per instrument. Set to `0` to disable                | `2000`  |
| [opentelemetry.metrics.runtime\_metrics](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-runtime_metrics)       | Export Go runtime metrics (memory, goroutines, GC). Set to `false` to disable                      | `true`  |
| [opentelemetry.metrics.api\_metrics](/docs/tyk-oss-gateway/configuration#opentelemetry-metrics-api_metrics)               | Custom metric instrument definitions. See [Custom Metrics](/docs/api-management/metrics/custom-metrics) | —       |

All fields are also documented in the [Tyk Gateway Configuration Reference](/docs/tyk-oss-gateway/configuration#opentelemetry).

<Note>
  Root-level configuration such as `opentelemetry.enabled` and `opentelemetry.endpoint` still work for traces but are deprecated. Use `opentelemetry.traces.*` for new deployments.
</Note>

### Cardinality Control

Each unique combination of dimension values creates a separate time series in your metrics backend. For example, a metric with 100 APIs × 5 methods × 10 status codes = 5,000 time series. Adding dimensions that have many possible values (such as user IDs or free-text fields) can create millions of time series, causing high storage costs and potential out-of-memory crashes.

The `opentelemetry.metrics.cardinality_limit` field caps how many unique attribute combinations are tracked per metric instrument:

* **Default limit:** 2,000 combinations per instrument
* **When the limit is reached:** New attribute combinations are aggregated into an overflow bucket marked with `otel.metric.overflow=true`
* **Existing time series are not affected**; only new combinations are blocked
* **To disable the limit:** Set to `0` (not recommended for production)

You can alert on cardinality overflow using this PromQL expression:

```promql theme={null}
increase(some_metric{otel_metric_overflow="true"}[5m]) > 0
```

This lets you catch runaway cardinality before costs escalate.

## Tyk Cloud

On Tyk Cloud, metrics export is enabled per environment via the **Telemetry** settings in the Tyk Cloud UI. A **Telemetry entitlement** is required; contact your account team if it is not available on your plan.

**Supported export destinations on Tyk Cloud:**

* New Relic
* Elastic (Elasticsearch / OpenSearch)
* Dynatrace
* Custom OTLP endpoint (any OTLP-compatible backend)

Tyk Cloud exports the [default gateway metrics](/docs/api-management/metrics/default-metrics) through the telemetry pipeline. Custom metric configuration is not currently self-service on Tyk Cloud; contact Tyk support to request it.

## Metrics Pumps

[Tyk Pump](/docs/api-management/tyk-pump) can expose metrics derived from the traffic logs that the Gateway stores in Redis, the same traffic logs used for [Dashboard Analytics](/docs/api-management/dashboard-analytics). This is an older, separate mechanism: computed by Tyk Pump after the fact from traffic log records, not by Tyk Gateway in real time, so it can only produce traffic-derived counters and histograms (status codes, latency, and whatever traffic log fields you tag). It has no visibility into Gateway's own runtime health or configuration state.

There are three Metrics Pumps, [documented here](/docs/api-management/metrics/metrics-pumps), that target different backends:

* Prometheus
* DogStatsD (Datadog)
* StatsD (not to be confused with the native Gateway [StatsD instrumentation](#statsd-instrumentation))

Metrics Pumps aren't deprecated, and existing deployments can keep using them, but we recommend [OpenTelemetry Metrics](#opentelemetry-metrics) where you can: it's more powerful and flexible, and doesn't require the Redis and Tyk Pump hop to get metrics out.

## Deprecated Backends

### New Relic Instrumentation

<Warning>
  This instrumentation method is deprecated. New Relic users should migrate to the [OpenTelemetry metrics exporter](/docs/api-management/logs-metrics#opentelemetry-metrics) with a New Relic OTLP endpoint. The OTel approach provides richer metrics, more dimensions, and does not require a New Relic agent license.
</Warning>

Tyk Gateway has been instrumented for New Relic metrics since v2.5. Add the following to `tyk.conf` to enable it:

```json theme={null}
{
  "newrelic": {
    "app_name": "<app-name>",
    "license_key": "<license_key>"
  }
}
```

### StatsD Instrumentation

<Warning>
  This instrumentation method is deprecated. We recommend using [OpenTelemetry metrics](/docs/api-management/logs-metrics#opentelemetry-metrics) instead, which provides richer metrics and works with any modern observability backend.
</Warning>

Tyk Gateway, Pump, and Dashboard have been instrumented for [StatsD](https://github.com/etsy/statsd) monitoring. StatsD is a network daemon that listens for statistics sent over UDP or TCP and forwards aggregates to pluggable backend services.

<Note>
  Not to be confused with Tyk Pump's `statsd`/`dogstatsd` [Metrics Pumps](#metrics-pumps) above: those export traffic-log-derived request metrics, a different mechanism from this internal system instrumentation.
</Note>

#### Configuring StatsD

To enable StatsD instrumentation, set the environment variable `TYK_INSTRUMENTATION=1` and configure `statsd_connection_string` in each component's config file. This field specifies how to connect to the StatsD server (host, port, and optional configuration).

You can also set `statsd_prefix` to a custom value to differentiate metrics between environments (for example, separate prefixes for production and staging).

For Tyk Pump specifically, both fields sit at the top level of `pump.conf`, alongside `log_level` and the other [global settings](/docs/api-management/tyk-pump#configuring-tyk-pump).

#### StatsD Keys

| Key                                                        | Description                                          |
| ---------------------------------------------------------- | ---------------------------------------------------- |
| `gauges.<prefix>.Load.rps`                                 | API traffic handled by Gateway (requests per second) |
| `counters.<prefix>.SystemAPICall.called.count`             | Gateway API call count                               |
| `timers.<prefix>.SystemAPICall.success`                    | Gateway API response time                            |
| `counters.<prefix>.SystemAPICall.SystemCallComplete.count` | Dashboard API request count                          |
| `counters.<prefix>.DashSystemAPIError.*`                   | Dashboard API error reporting                        |
| `counters.<prefix>.record.count`                           | Number of records processed by Pump                  |