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

> Learn how to configure Tyk 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, Tyk Dashboard, Tyk MDCB, Tyk Developer Portal | **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](https://tyk.io/docs/developer-support/deprecation.md#understanding-deprecation-and-end-of-life-eol) | Legacy New Relic agent integration available since Tyk Gateway v2.5. |
| [StatsD Instrumentation](#statsd-instrumentation) | Tyk Gateway, Tyk Pump, Tyk Dashboard | [Deprecated](https://tyk.io/docs/developer-support/deprecation.md#understanding-deprecation-and-end-of-life-eol) | Legacy StatsD protocol export for these three components. |

## OpenTelemetry Metrics

### Availability

| Component | Version | Edition |
| :- | :- | :- |
| Tyk Gateway | Available since [v5.13.0](https://tyk.io/docs/developer-support/release-notes/gateway.md#5-13-0-release-notes) | Community & Enterprise |
| Tyk Dashboard | Available since v5.16.0 | Enterprise |
| Tyk MDCB | Available since v2.14.0 | Enterprise |
| Tyk Developer Portal | Available since v1.20.0 | Enterprise |

### Tyk Gateway Metrics

Tyk Gateway natively exports metrics via the OpenTelemetry Protocol (OTLP). When enabled, it pushes standard RED metrics (Rate, Errors, Duration) plus Go runtime and configuration state metrics to any OTLP-compatible backend.

For a complete reference, see:

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

### Control Plane Metrics

Tyk Dashboard, Tyk MDCB, and Tyk Developer Portal export metrics through the same OTLP pipeline:

| Component | What It Covers |
| - | - |
| Tyk Dashboard | Gateway node registry and fleet state, license capacity and expiry, request rate, errors, and duration for its management API, change propagation, dependency pool pressure, object counts, and Go runtime |
| Tyk MDCB | Gateway connectivity and churn, RPC load, configuration and key sync health, analytics ingestion, dependency and self health, and Go runtime |
| Tyk Developer Portal | Provider sync health with Tyk Dashboard, database and storage health, and process uptime |

For every metric, see [Default Metrics](https://tyk.io/docs/api-management/metrics/default-metrics.md).

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

## Configuration Options

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

### 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"
    }
  }
}
```

Tyk Dashboard and Tyk MDCB use the same `opentelemetry.metrics` block, in `tyk_analytics.conf` and `tyk_sink.conf` respectively. For a worked example of both, see [Get Started with Tyk Observability](https://tyk.io/docs/api-management/observability-getting-started.md#add-tyk-dashboard-tyk-mdcb-and-tyk-developer-portal).

Tyk Developer Portal uses a separate `OpenTelemetry.Metrics` configuration section instead of the `opentelemetry.metrics` block. Set it with the `PORTAL_OPENTELEMETRY_METRICS_*` or `TYK_PORTAL_OPENTELEMETRY_METRICS_*` environment variables. For a worked example, see [Configure Tyk Developer Portal](https://tyk.io/docs/api-management/observability-getting-started.md#configure-tyk-developer-portal). For what it exports, see [Control Plane Metrics](#control-plane-metrics).

### 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 Tyk Gateway metrics](https://tyk.io/docs/api-management/metrics/default-metrics.md) to the same OTLP endpoint configured for traces.

### Reference

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

All fields are also documented in the [Tyk Gateway Configuration Reference](https://tyk.io/docs/tyk-oss-gateway/configuration.md#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.

#### Control Plane Fields

Tyk Dashboard and Tyk MDCB add two fields that Tyk Gateway does not have:

| Field | Description | Default |
| - | - | - |
| `control_plane_id` | Identifies this control plane. This is a top-level setting, not part of the `opentelemetry.metrics` block. The environment variable is `TYK_DB_CONTROLPLANEID` for Tyk Dashboard and `TYK_MDCB_CONTROLPLANEID` for Tyk MDCB. Leave it blank to generate it automatically and share it with the other component through Redis. | None (generated automatically if blank) |
| `opentelemetry.metrics.deployment_environment` | Exported as the `deployment.environment` resource attribute. Set the same value on Tyk Dashboard, Tyk MDCB, and Tyk Developer Portal so that you can correlate their metrics. | `unknown` |

Tyk Developer Portal sets `deployment.environment` with its `DeploymentEnvironment` field, which also defaults to `unknown`.

#### Metric Family Flags

Each metric family has its own on/off flag in the metrics configuration of its component. Every flag defaults to `true`, so when you enable metrics, the component exports all of its families. To turn off a family, set its flag to `false`.

| Component | Family Flags |
| - | - |
| Tyk Dashboard | `gateway_metrics`, `license_metrics`, `http_metrics`, `certificate_metrics`, `dependency_metrics`, `notification_metrics`, `objects_metrics.enabled`, `health_metrics`, `runtime_metrics`, `meta_metrics` |
| Tyk MDCB | `dataplanes_metrics`, `rpc_metrics`, `sync_metrics`, `analytics_metrics`, `dependency_metrics`, `health_metrics`, `expiry_metrics`, `runtime_metrics`, `meta_metrics` |
| Tyk Developer Portal | `ProviderMetrics`, `HealthMetrics` |

Each flag also has an environment variable, for example `TYK_DB_OPENTELEMETRY_METRICS_GATEWAYMETRICS`, `TYK_MDCB_OPENTELEMETRY_METRICS_RPCMETRICS`, or `PORTAL_OPENTELEMETRY_METRICS_PROVIDERMETRICS`.

Tyk Dashboard has two more settings under `opentelemetry.metrics.objects_metrics`:

| Field | Description | Default |
| - | - | - |
| `collection_interval` | How often Tyk Dashboard refreshes the object counts, in seconds. Valid values are 10 to 86400. | `300` |
| `governance` | Export the governance metrics. These also need a license that includes governance. | `true` |

For what a metric family is, see [Metric Groups and Families](https://tyk.io/docs/api-management/metrics/metrics-concepts.md#metric-groups-and-families).

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

The same limit and overflow behavior apply to Tyk Dashboard, Tyk MDCB, and Tyk Developer Portal. Their label sets depend on fleet and organization size, not on request-level data. Overflow is much rarer than on Tyk Gateway, but you can use the same PromQL pattern to alert on it.

## 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](https://tyk.io/docs/api-management/metrics/default-metrics.md) through the telemetry pipeline. Custom metric configuration is not currently self-service on Tyk Cloud; contact Tyk support to request it.

Tyk Dashboard and Tyk MDCB metrics are not available through the Tyk Cloud Telemetry settings.

## Metrics Pumps

[Tyk Pump](https://tyk.io/docs/api-management/tyk-pump.md) can expose metrics derived from the traffic logs that Tyk Gateway stores in Redis, the same traffic logs used for [Tyk Dashboard Analytics](https://tyk.io/docs/api-management/dashboard-analytics.md). This is an older, separate mechanism: computed by Tyk Pump after the fact from traffic log records, not by the 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 the gateway's own runtime health or configuration state.

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

* Prometheus
* DogStatsD (Datadog)
* StatsD (not to be confused with the native Tyk 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](https://tyk.io/docs/api-management/logs-metrics.md#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.

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](https://tyk.io/docs/api-management/logs-metrics.md#opentelemetry-metrics) instead, which provides richer metrics and works with any modern observability backend.

Tyk Gateway, Tyk Pump, and Tyk 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.

#### 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](https://tyk.io/docs/api-management/tyk-pump.md#configuring-tyk-pump).

#### StatsD Keys

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