Telemetry

TrustGate exports one OpenTelemetry log record per request — model, tokens, cost, latency breakdown, policy chain, and routing attempts — off the critical path.

Telemetry is the per-request event that the metrics worker builds and ships off the critical path. Each event captures everything needed to analyze cost, latency, routing, and policy decisions. TrustGate exports events with OpenTelemetry to your collector (NeuralTrust SaaS or your own).

On NeuralTrust, those records feed Activity, Analytics, and Telemetry Alerts. The field-level contract used by AlertEngine is documented in the Event schema.

How export works

1. The proxy finishes the request (including streamed responses).
2. A background worker builds a structured event (metadata; bodies are not in the default metadata stream).
3. The event is exported as an OpenTelemetry log record to the configured collector endpoint.
4. Downstream systems (NeuralTrust metadata store, your SIEM, billing pipelines) consume the collector output.

Export never blocks the client response path — see Metrics worker.

Configuration

Telemetry is configured globally by environment and can be refined per gateway.

Variable	Default	Meaning
TELEMETRY_ENABLED	true	Toggle telemetry.
TELEMETRY_ENABLE_REQUEST_TRACES	true	Include request traces.
TELEMETRY_ENABLE_PLUGIN_TRACES	true	Include per-policy traces.
TELEMETRY_EXPORTERS_FILE	config/telemetry.yaml	Path to an exporters YAML file. It wins when it parses. The chart pins this empty so the env vars below are the only source.
TELEMETRY_EXPORTERS_METADATA	—	Type token (otlp) or a YAML/JSON list of named exporters. Requires v0.37.0+.
TELEMETRY_EXPORTERS_RAW	—	Type token (postgres, otlp) or a YAML/JSON list of named exporters. Requires v0.37.0+.
OTEL_EXPORTER_OTLP_ENDPOINT	—	OpenTelemetry collector endpoint (e.g. https://collector.example:4318). Required for token-only otlp.
OTEL_EXPORTER_OTLP_PROTOCOL	—	Transport, typically http/protobuf or grpc.
OTEL_EXPORTER_OTLP_HEADERS	—	Extra headers (auth tokens, tenant keys).
OTEL_EXPORTER_OTLP_INSECURE	—	Allow non-TLS (local/dev only).
OTEL_EXPORTER_OTLP_COMPRESSION	—	e.g. gzip.
OTEL_EXPORTER_OTLP_TIMEOUT	—	Export timeout (ms).

Per gateway, telemetry can define exporters, static extra_params appended to every event, trace toggles, and a header_mapping that copies inbound headers into event fields. Process-level OTEL_EXPORTER_OTLP_* values supply defaults when a gateway opts into OpenTelemetry export.

Exporters

A gateway’s telemetry.exporters[] selects where its events go:

name	Settings	Notes
otlp	endpoint, headers, protocol, …	Export each request as an OpenTelemetry log record. Metadata class uses event name trustgate.<version>.metadata.

On NeuralTrust Hybrid / SaaS, the control plane wires the collector endpoint for you (see Deployment overview). For self-managed collectors, set OTEL_EXPORTER_OTLP_ENDPOINT (and headers) to your OpenTelemetry Collector.

What the event carries

Events are versioned (schema_version) and carry a kind of llm or mcp. Each includes, among others:

Group	Fields
Identity	trace_id, gateway_id, tenant_id, consumer, session_id, turn_id.
Request	method, path, provider, registry id, requested vs resolved model, temperature, max tokens, stream flag.
Response	status code, latency, finish reason, streaming.
Usage	prompt / completion / total tokens, cached input, reasoning output.
Cost	prompt / completion / total USD. Rates come from registry contract pricing when set, otherwise the models.dev catalog. Unpriced models omit cost.
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.

Attributes follow OpenTelemetry HTTP and GenAI conventions where applicable (http.request.method, gen_ai.request.model, gen_ai.usage.*, …), plus trustgate.* extensions for gateway-specific fields. Prompt and response bodies are not included in the default metadata export used by alerts and analytics.

Using the data

Surface	Use
Activity	Per-request forensics.
Analytics	Volume, cost, latency, policy actions.
Telemetry Alerts	Detection rules (error rate, latency, auth anomalies, …).
Event schema	Fields AlertEngine rules match on.
Your collector / SIEM	Forward from the OpenTelemetry Collector pipeline.

The attempts and policy_chain data make it possible to reconstruct how each request was routed and which policies fired.