OpenTelemetry Kong Gateway Integration

Kong Gateway provides a native OpenTelemetry plugin to capture proxy latencies, upstream traces, traffic metrics, and access logs. By configuring this plugin, you send your telemetry data directly to SigNoz.

For traces and structured logs from one SigNoz-built plugin, see the SigNoz Plugin guide. To compare both approaches, see Kong Gateway Monitoring.

Most steps remain identical. To adapt this guide, update the endpoint and remove the ingestion key header as shown in Cloud vs Self-Hosted.

Prerequisites

For OpenTelemetry Traces: Kong Gateway version 3.0+ (Enterprise or OSS).
For OpenTelemetry Logs: Kong Gateway version 3.8+ (Enterprise or OSS).
For OpenTelemetry Metrics: Kong Gateway Enterprise version 3.13+. (The latest open-source community edition release is 3.9.x, which predates native OpenTelemetry metrics support).
An instance of SigNoz (Cloud or Self-Hosted).

Enable Kong's Tracer

Kong's built-in instrumentations produce the spans, and the plugin only exports them. Two settings in kong.conf control the tracer. Both defaults produce no usable trace data: tracing_instrumentations is off, and tracing_sampling_rate is 0.01, which is 1% of requests.

Set both values on every Kong node:

tracing_instrumentations = all
tracing_sampling_rate    = 1.0

If you run Kong in Docker or on Kubernetes, set the same values as environment variables:

KONG_TRACING_INSTRUMENTATIONS=all
KONG_TRACING_SAMPLING_RATE=1.0

Restart Kong to apply the settings.

The value all enables every instrumentation, which costs memory and bandwidth on a gateway with high traffic. After traces arrive in SigNoz, you can decrease tracing_sampling_rate and replace all with the phases you need. The available phases include request, router, balancer, db_query, dns_query, and http_client. Kong's tracing configuration reference lists all of them.

Metrics and logs do not depend on the tracer.

Configure OpenTelemetry Export

Configure the opentelemetry plugin either via declarative config (decK) or via the Kong Ingress Controller in Kubernetes.

_format_version: "3.0"
_transform: true
 
plugins:
  - name: opentelemetry
    config:
      traces_endpoint: "https://ingest.<region>.signoz.cloud:443/v1/traces"
      logs_endpoint: "https://ingest.<region>.signoz.cloud:443/v1/logs"
      metrics:
        endpoint: "https://ingest.<region>.signoz.cloud:443/v1/metrics"
        push_interval: 10
        enable_bandwidth_metrics: true
        enable_latency_metrics: true
        enable_request_metrics: true
        enable_upstream_health_metrics: true
      headers:
        signoz-ingestion-key: "<your-ingestion-key>"
      resource_attributes:
        service.name: "<service_name>"
      queue:
        max_batch_size: 200
        max_coalescing_delay: 3

Verify these values:

<region>: Your SigNoz Cloud region
<your-ingestion-key>: Your SigNoz ingestion key
<service_name>: The name of your service

Sync your state via Kong's Admin API:

deck gateway sync kong-state.yaml --kong-addr <YOUR-KONG-ADMIN-URL>

Apply a KongClusterPlugin to enable the plugin globally across all services managed by the Ingress Controller.

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: opentelemetry-global
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: "true"
plugin: opentelemetry
config:
  traces_endpoint: "https://ingest.<region>.signoz.cloud:443/v1/traces"
  logs_endpoint: "https://ingest.<region>.signoz.cloud:443/v1/logs"
  metrics:
    endpoint: "https://ingest.<region>.signoz.cloud:443/v1/metrics"
    push_interval: 10
    enable_bandwidth_metrics: true
    enable_latency_metrics: true
    enable_request_metrics: true
    enable_upstream_health_metrics: true
  headers:
    signoz-ingestion-key: "<your-ingestion-key>"
  resource_attributes:
    service.name: "<service_name>"

Verify these values:

<region>: Your SigNoz Cloud region
<your-ingestion-key>: Your SigNoz ingestion key
<service_name>: The name of your service

Apply the file to your cluster:

kubectl apply -f kong-plugin-otel.yaml

To collect only specific signal types, remove the endpoints you don't need:

Traces only: remove logs_endpoint and the metrics block
Logs only: remove traces_endpoint and the metrics block
Metrics only: remove traces_endpoint and logs_endpoint

Available Telemetry

Kong instruments each proxied request as an OTel span with child spans for each phase:

Proxy latency: time Kong spends routing the request before forwarding it upstream
Plugin execution: time spent inside each enabled plugin (e.g. auth, rate-limiting)
DNS resolution: upstream hostname lookup time
Upstream latency: time waiting for the upstream service to respond

Each span carries standard HTTP attributes: http.method, http.url, http.host, http.scheme, http.flavor, and net.peer.ip.

Kong supports W3C TraceContext, B3/B3-single (Zipkin), Jaeger, OpenTracing, Datadog, AWS X-Ray, and GCP propagation formats. Existing distributed traces from upstream or downstream services pass through without extra configuration.

Requires Kong Gateway Enterprise v3.13+.

Metric	Type	What it measures
`kong.latency.total`	Histogram	End-to-end request duration
`kong.latency.upstream`	Histogram	Time waiting for the upstream service
`kong.latency.internal`	Histogram	Kong's own processing time (plugins, routing)
`http.server.request.count`	Sum	Incoming requests, tagged by service, route, consumer, and HTTP status
`http.server.request.size`	Histogram	Request body size in bytes
`http.server.response.size`	Histogram	Response body size in bytes
`kong.nginx.connection.count`	Gauge	Active Nginx connections by state
`kong.upstream.target.status`	Gauge	Health status of each upstream target

Kong pushes all metrics over OTLP on the push_interval you configure (default: 60 seconds, set to 10 in the example above for faster feedback). The enable_bandwidth_metrics, enable_latency_metrics, enable_request_metrics, and enable_upstream_health_metrics flags in the plugin config control which metric groups Kong collects.

Validate

Verify your data appears in SigNoz:

Open Services to confirm <service_name> appears in the list.
Head to Traces to browse distributed traces for your Kong routes.
Open Metrics Explorer and query kong.latency.total or kong.nginx.connection.count.
Head to Logs and filter by service.name = <service_name> to read access logs.

Troubleshooting

Traces do not appear in SigNoz

Verify that tracing_instrumentations is set to a value other than off. With the tracer off, Kong produces no spans, and the plugin reports no error. Also verify tracing_sampling_rate. At the default 0.01, only 1 request in 100 produces a trace. A gateway with low traffic can therefore appear to send nothing. Tracing instrumentations do not run in stream mode.

Metrics do not appear in SigNoz

Verify your Kong Gateway version and edition. Kong Open-Source (CE) presently terminates at version 3.9 and lacks the config.metrics object. Using the metrics configuration against Kong 3.12 or older produces a schema validation error.

Schema Validation Error on "metrics"

Ensure you pass metrics as an object containing endpoint, rather than a flat string. Earlier plugin schema versions rejected the metrics map entirely. See Kong OpenTelemetry plugin schema.

Setup OpenTelemetry Collector (Optional)

Avoid hardcoding the SigNoz cloud endpoints in your Kong instance by configuring Kong to point to a local OpenTelemetry Collector instead.

Ensure your OpenTelemetry Collector instance exposes the otlp HTTP receiver on port 4318.
Update the Kong Plugin configuration to point to your collector:
- traces_endpoint: http://<your-collector-ip>:4318/v1/traces
- logs_endpoint: http://<your-collector-ip>:4318/v1/logs
- endpoint: http://<your-collector-ip>:4318/v1/metrics
Remove the signoz-ingestion-key header from the Kong configuration, and let your Collector append the authentication header to SigNoz.

Read the Collector configuration guide for implementation details.

Next Steps

Import the Kong Gateway Dashboard template to monitor traffic in real-time.
Set up Alerts for routing anomalies or upstream timeouts.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.