Skip to main content

Tracing

Observra creates client-side spans around supported LLM traffic and injects W3C trace context into gateway-bound requests.

Recorded attributes​

When available from provider request and response bodies, spans include:

  • Provider and gateway route
  • Model name
  • Input and output values
  • Prompt and completion token counts
  • Request latency
  • Guardrail violations
  • Error status and exception data

Framework instrumentation adds agent, chain, tool, and LLM spans where supported.

Trace hierarchy​

The SDK uses OpenTelemetry context propagation. Provider calls inside an active framework or OpenTelemetry span share a trace and become nested children. This works with synchronous code, async/await, and threads through OpenTelemetry context variables.

LangGraph example hierarchy:

AGENT: LangGraph
└── CHAIN: answer
    └── LLM: mistral.generate

Gateway correlation​

For gateway-routed calls, Observra injects a W3C traceparent header. Gateway observations can use it to correlate gateway records with client-side spans.

Trace context is added only to supported provider calls routed through Observra. Unrelated outbound traffic is not modified.

OpenTelemetry isolation​

Observra creates a private TracerProvider for each configuration. It never calls opentelemetry.trace.set_tracer_provider(), so it does not replace an application's global OpenTelemetry provider or exporter.

The export queue is bounded. Under exporter failure or slow delivery, older spans are dropped rather than allowing unbounded memory growth.

Failure behaviour​

Span creation, attributes, guardrail scanning, and export are fail-open. They are isolated from the provider request path. Gateway, network, authentication, quota, and provider errors remain visible to application code.

Next​