Export traces with OTLP

The observability exporter projects persisted session events into traces and sends them over OTLP HTTP/JSON. Use it to inspect agent turns, tools, and outcome evaluations in an external backend without instrumenting your agent. Langfuse and Litefuse accept this wire format.

How export works

Harness -> persisted Kafka session events -> observability exporter -> OTLP endpoint
                                               |
                                      Registry internal API
                                      (policy and credentials)

The registry selects a binding when you create a session. The exporter reads its pinned configuration through an internal resolver, projects eligible turns, and queues them durably. It resolves current credentials again before delivery. The public event list and SSE stream remain available without the exporter; neither is the exporter's source of truth.

The default exporter stores checkpoints and delivery records in Kafka. Registry still uses its own Postgres database. An explicit legacy exporter Postgres backend also reads Kafka session events, but supports only metadata-only capture. See deploy the exporter.

From session events to traces

An event records a fact in a session, such as user input, a tool invocation, or a turn ending. The exporter correlates these persisted events into a turn, then projects each eligible, sampled turn into a trace. A trace contains a root span for the turn and child spans for the work within it. Langfuse displays these spans as observations. One event does not necessarily create one span, and one session can contain multiple traces.

For a user message, appending user.message alone does not start a projected turn. The exporter matches it to a session.user_event_processed marker through user_event_id; acceptance establishes the turn's anchor event. Within that turn, paired model-summary and evaluation events form child spans, while tool invocations and results are correlated through their explicit IDs. These children share the turn's trace ID and use its root span as their parent, rather than forming a hierarchy inferred from message text.

Arrows within Trace A show span parentage, not execution order. Children appear only when their corresponding events are projected. A subsequent turn produces a separate Trace B; both traces share session.id, but have different trace IDs.

A terminal event closes the turn so the exporter can queue its completed trace. An idle event with stop_reason: requires_action leaves the turn open: accepted tool results or confirmations continue that turn instead of creating another trace. The exporter derives timing, status, and reported usage from source events; authorized raw capture also adds selected message and tool content as span I/O. It does not invent missing measurements. Trace and span IDs are deterministic, so replaying the same source events or retrying delivery preserves their identities.

Supported OTLP configuration

The exporter sends Content-Type: application/json and x-langfuse-ingestion-version: 4. It requires a public HTTPS destination, validates DNS addresses, and connects directly to an approved address. It rejects private, link-local, and metadata-service addresses, follows no redirects, and does not use ambient proxies. A private collector or a local HTTP receiver is not a supported target.

What appears in a trace

Each projected primary-path turn has a deterministic trace ID and one root observation. Multiple turns in the same session have different traces, grouped by the namespaced session.id value <workspace_id>:<session_id>. Subagent subpaths are not projected into an inferred hierarchy.

A model summary is not a provider generation or a record of every LLM request. The exporter does not infer missing token usage, prices, or cost. A tool error does not by itself make the turn fail. Tool approval records permission, not execution or completion.

Metadata-only capture excludes prompts, responses, tool names, arguments, results, and error text. With authorized raw capture, root/tool input and output use langfuse.observation.input and langfuse.observation.output as JSON strings. Root output contains non-partial assistant text messages from the turn, not a guaranteed final answer. See capture modes and privacy.

Newly attributed traces include available registry-approved agent ID/version, harness name/mode, binding/config version, and configured environment/release in trace and observation metadata. Agent version also maps to langfuse.version; environment/release map to langfuse.environment and langfuse.release. These values come from the persisted delivery context, not arbitrary session metadata. Old queued traces are not enriched from current configuration.

Sampling and delivery

• sample_rate: 0 exports no eligible turns; 1 selects all of them. A selected trace includes its root and children together. Sampling is pinned with the session's configuration and stable across replay; it is not a fresh random decision on every retry.
• In Kafka mode, source progress, checkpoint state, and queued deliveries commit transactionally. External HTTP acceptance cannot share that transaction: delivery is at-least-once, and a retry can send the same deterministic trace again.
• Transport failures and OTLP 429, 502, 503, and 504 retry with backoff. Retry-After is bounded to one hour. 401/403 causes one fresh audited credential resolution and resend; another rejection is terminal. Do not repeatedly rotate credentials to hide a wrong project.
• Kafka retries pause a delivery partition; they are not a per-binding fairness guarantee. Changing settings does not replay terminally suppressed sessions or backfill historical traces.

Relationship to gateway telemetry

AI Gateway telemetry describes traffic that passes through the gateway. This exporter describes agent execution derived from session events. Their deployment configuration and OTLP capabilities are separate. Enabling one does not enable the other or promise an automatically joined distributed trace.

What's next