Metrics Configuration in Tyk Gateway

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	Tyk Gateway	Recommended	Native OTLP metrics export. Works with any OpenTelemetry-compatible backend.
Metrics Pumps	Tyk Pump	Legacy	Prometheus, StatsD, or DogStatsD metrics derived from traffic logs. Relevant for existing deployments.
New Relic Instrumentation	Tyk Gateway	Deprecated	Legacy New Relic agent integration available since Gateway v2.5.
StatsD Instrumentation	Tyk Gateway, Pump, Dashboard	Deprecated	Legacy StatsD protocol export for Gateway, Pump, and Dashboard.

OpenTelemetry Metrics

Availability

Component	Version	Edition
Tyk Gateway	Available since v5.13.0	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 below. For a complete reference, see:

Default Metrics: all metrics exported automatically (RED, Go runtime, configuration state)
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.

Enable Metrics

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

{
  "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:

{
  "opentelemetry": {
    "traces": {
      "enabled": true,
      "endpoint": "otel-collector:4317"
    },
    "metrics": {
      "enabled": true
    }
  }
}

This is enough to start exporting default Gateway metrics to the same OTLP endpoint configured for traces.

Reference

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

All fields are also documented in the Tyk Gateway Configuration Reference.

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

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:

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 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 can expose metrics derived from the traffic logs that the Gateway stores in Redis, the same traffic logs used for 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, that target different backends:

Prometheus
DogStatsD (Datadog)
StatsD (not to be confused with the native Gateway StatsD instrumentation)

Metrics Pumps aren’t deprecated, and existing deployments can keep using them, but we recommend 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

This instrumentation method is deprecated. New Relic users should migrate to the OpenTelemetry metrics exporter 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:

{
  "newrelic": {
    "app_name": "<app-name>",
    "license_key": "<license_key>"
  }
}

StatsD Instrumentation

This instrumentation method is deprecated. We recommend using OpenTelemetry metrics instead, which provides richer metrics and works with any modern observability backend.

Tyk Gateway, Pump, and Dashboard have been instrumented for StatsD monitoring. StatsD is a network daemon that listens for statistics sent over UDP or TCP and forwards aggregates to pluggable backend services.

Not to be confused with Tyk Pump’s statsd/dogstatsd 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.

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

Getting Started

Deploy Tyk

Design & Create APIs

Secure APIs

Control Traffic

Routing Traffic

Transform Traffic

Observe APIs

Maintain APIs

Platform Administration

Guides

Reference

Developer Support

Metrics Configuration in Tyk Gateway

Introduction

OpenTelemetry Metrics

Availability

Tyk Gateway Metrics

Supported Backends

Configuration Options

Enable Metrics

Traces and metrics together

Reference

Cardinality Control

Tyk Cloud

Metrics Pumps

Deprecated Backends

New Relic Instrumentation

StatsD Instrumentation

Configuring StatsD

StatsD Keys

​Introduction

​OpenTelemetry Metrics

​Availability

​Tyk Gateway Metrics

​Supported Backends

​Configuration Options

​Enable Metrics

​Traces and metrics together

​Reference

​Cardinality Control

​Tyk Cloud

​Metrics Pumps

​Deprecated Backends

​New Relic Instrumentation

​StatsD Instrumentation

​Configuring StatsD

​StatsD Keys

Introduction

OpenTelemetry Metrics

Availability

Tyk Gateway Metrics

Supported Backends

Configuration Options

Enable Metrics

Traces and metrics together

Reference

Cardinality Control

Tyk Cloud

Metrics Pumps

Deprecated Backends

New Relic Instrumentation

StatsD Instrumentation

Configuring StatsD

StatsD Keys