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

# OpenTelemetry Metrics Configuration in Tyk Gateway

> Learn how to configure Tyk Gateway to export metrics using OpenTelemetry Protocol (OTLP) to backends including Prometheus, Grafana, and Datadog.

## Availability

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

## Overview

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 Gateway supports three ways to export metrics:

| Method                                                  | Status          | Description                                                                  |
| ------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------- |
| [OpenTelemetry Metrics](#opentelemetry-metrics)         | **Recommended** | Native OTLP metrics export. Works with any OpenTelemetry-compatible backend. |
| [New Relic Instrumentation](#new-relic-instrumentation) | Deprecated      | Legacy New Relic agent integration available since Gateway v2.5.             |
| [StatsD Instrumentation](#statsd-instrumentation)       | Deprecated      | Legacy StatsD protocol export for Gateway, Pump, and Dashboard.              |

## In-Product Analytics

If you don't want to set up your own metrics pipeline and dashboard, Tyk Dashboard provides built-in traffic analytics out of the box. This gives you a historical view of API usage, traffic patterns, and response times (including request counts, response time distribution, and error rates), tracked per API and per client key, with no third party observability tools required.

This analytics pipeline uses [Tyk Pump](/api-management/tyk-pump) or [Tyk MDCB](/api-management/mdcb) to aggregate [traffic logs](/api-management/tyk-pump#api-traffic-logs) from Tyk Gateway and store them in the Dashboard's [analytics storage](/api-management/dashboard-configuration#data-storage-solutions). You can also use Tyk Pump to export analytics to [external backends](/api-management/tyk-pump#external-data-stores) such as Elasticsearch, InfluxDB, and Kafka.

## OpenTelemetry 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 without requiring extra infrastructure alongside Tyk.

For a complete reference, see:

* [Default Metrics](/api-management/metrics/default-metrics): all metrics exported automatically (RED, Go runtime, configuration state)
* [Custom Metrics](/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
* Any Prometheus-compatible endpoint with remote write

## Configuration Options

Metrics can be enabled independently; distributed tracing does not need to be configured. To configure distributed tracing alongside metrics, see [Distributed Tracing](/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](/api-management/metrics/default-metrics) to the same OTLP endpoint configured for traces.

### Reference

| Field                                                                                                                | Description                                                                                        | Default |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------- |
| [opentelemetry.metrics.enabled](/tyk-oss-gateway/configuration#opentelemetry-metrics-enabled)                        | Enable OTLP metrics export                                                                         | `false` |
| [opentelemetry.metrics.exporter](/tyk-oss-gateway/configuration#opentelemetry-metrics-exporter)                      | Export protocol: `grpc` or `http`                                                                  | `grpc`  |
| [opentelemetry.metrics.endpoint](/tyk-oss-gateway/configuration#opentelemetry-metrics-endpoint)                      | OTLP collector endpoint. Defaults to `opentelemetry.traces.endpoint` if not set                    | —       |
| [opentelemetry.metrics.connection\_timeout](/tyk-oss-gateway/configuration#opentelemetry-metrics-connection_timeout) | Connection timeout in seconds                                                                      | `1`     |
| [opentelemetry.metrics.headers](/tyk-oss-gateway/configuration#opentelemetry-metrics-headers)                        | Additional HTTP headers sent with each OTLP export request                                         | —       |
| [opentelemetry.metrics.tls](/tyk-oss-gateway/configuration#opentelemetry-metrics-tls)                                | TLS configuration for the OTLP connection                                                          | —       |
| [opentelemetry.metrics.export\_interval](/tyk-oss-gateway/configuration#opentelemetry-metrics-export_interval)       | How often metrics are pushed to the backend, in seconds                                            | `60`    |
| [opentelemetry.metrics.shutdown\_timeout](/tyk-oss-gateway/configuration#opentelemetry-metrics-shutdown_timeout)     | Maximum time allowed for a single export request, in seconds                                       | `30`    |
| [opentelemetry.metrics.cardinality\_limit](/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](/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](/tyk-oss-gateway/configuration#opentelemetry-metrics-api_metrics)               | Custom metric instrument definitions. See [Custom Metrics](/api-management/metrics/custom-metrics) | —       |

All fields are also documented in the [Tyk Gateway Configuration Reference](/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](/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.

## Deprecated Backends

### New Relic (deprecated)

<Warning>
  This instrumentation method is deprecated. New Relic users should migrate to the [OpenTelemetry metrics exporter](/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 (deprecated)

<Warning>
  This instrumentation method is deprecated. We recommend using [OpenTelemetry metrics](/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.

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

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