> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuraltrust.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry

> TrustGate streams a rich per-request event to Kafka — model, tokens, cost, latency breakdown, policy chain, and routing attempts — and can forward to TrustLens.

**Telemetry** is the per-request event that the [metrics worker](/trustgate/observability/metrics)
builds and ships off the critical path. Each event captures everything needed to analyze
cost, latency, routing, and policy decisions. The default sink is **Kafka**; a per-gateway
**OpenTelemetry (OTLP)** exporter and **TrustLens** forwarding are opt-in.

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

Per [gateway](/trustgate/concepts/gateways), `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's `telemetry.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. |

Process-level OTLP defaults come from the standard `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. The
`attempts` 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](/platform/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.