Configuration
Telemetry is configured globally by environment and refined per gateway.| Variable | Default | Meaning |
|---|---|---|
TELEMETRY_ENABLED | true | Toggle telemetry. |
TELEMETRY_KAFKA_TOPIC | agentgateway.requests | Destination topic. |
TELEMETRY_ENABLE_REQUEST_TRACES | true | Include request traces. |
TELEMETRY_ENABLE_PLUGIN_TRACES | true | Include per-policy traces. |
TELEMETRY_TRUSTLENS_ENABLED | false | Forward to TrustLens. |
TELEMETRY_TRUSTLENS_URL | — | TrustLens endpoint. |
telemetry can define its own exporters,
static extra_params appended to every event, trace toggles, and a header_mapping that
copies inbound headers into event fields.
Exporters
A gateway’stelemetry.exporters[] selects where its events go. Per-gateway exporters are
merged with (not a replacement for) the process-level Kafka default:
name | Settings | Notes |
|---|---|---|
kafka | { host, port, topic } | Stream events to a Kafka topic. |
otlp | OTLP endpoint / headers | Export each request as an OpenTelemetry log record (event.name = "gateway.request"). Only the logs signal is supported. |
OTEL_EXPORTER_OTLP_* environment
variables; a gateway opts in by adding an otlp exporter.
The event
Events are versioned (schema_version, currently 3) and carry a kind of llm or
mcp. Each includes, among others:
| Group | Fields |
|---|---|
| Identity | trace_id, gateway_id, team_id, consumer, session_id, turn_id, ip. |
| Request | method, path, provider, registry id, requested vs resolved model, temperature, max tokens, stream flag, prompt tokens. |
| Response | status code, latency, completion tokens, finish reason, streaming. |
| Usage | prompt / completion / total tokens, cached input, reasoning output. |
| Cost | prompt / completion / total USD. |
| Latency | total, provider, policies, routing, gateway (ms). |
| Attempts | per-registry attempts with fallback/pinned/route/outcome. |
| Policy chain | per-policy decision, stage, latency, score, flagged. |
Using the stream
Point any Kafka consumer at the topic to build dashboards, billing, or anomaly detection; or enable the TrustLens integration to forward events to NeuralTrust’s analytics. Theattempts and policy_chain arrays make it possible to reconstruct exactly how each
request was routed and which policies fired.
Once forwarded to NeuralTrust, these events also power Telemetry Alerts —
predefined and custom detection rules (elevated error rate, latency degradation,
authentication anomalies, rate-limit abuse, upstream-provider errors) that raise deduplicated
alerts and forward them to your SIEM.