Skip to main content
Traces appear on the Traces tab of a call in Call Logs. The LiveKit Python SDK and the Pipecat SDK forward spans for you. Any other stack can send spans over OTLP/HTTP. See Turn on traces.

Where traces fit

Voice Metrics tells you which turn was slow and which stage dominated it, on every call and with no setup. A trace tells you what ran inside that stage: the model request, the streaming adapter, each tool call. Use it when the stage number does not explain the delay. An LLM stage that was really a slow tool call looks the same as a slow model in a stage breakdown. In a span tree, the tool call span shows the time.

Reading the span tree

Tuner renders the trace against a time axis, with each bar positioned relative to the start of the session. Traces tab showing a span tree with agent_session as the root and nested agent_turn, llm_node, llm_request, tts_node, and user_turn spans, each with a duration and a bar on a shared time axis
  • Follow the widest bar at each level. Above, agent_turn is 4.84s and the tts_node under it is 4.62s, so synthesis took most of that turn.
  • Siblings overlap. llm_node and tts_node both start at 00:00, because synthesis streams on the first tokens. Children do not sum to their parent, the same way the pipeline stages do not sum to TTFB.
  • Collapse large traces. The call above has 171 spans. Collapse to the turn level, then expand the one turn you care about. Click a span to open its details. Span detail panel showing the Span, Timing, Status, Attributes, and Resource groups for a turn span lasting 11.52 seconds Span names come from your framework. See LiveKit traces or Pipecat traces.

Turn on traces

Setup lives with your integration.

LiveKit traces

Install the traces extra of tuner-livekit-sdk (Python, 0.1.10 or later).

Pipecat traces

Install the traces extra of tuner-pipecat-sdk (0.2.8 or later) and set enable_tracing=True.

Custom stack traces

Export spans from any stack with an OTLP HTTP exporter.
On LiveKit and Pipecat, the SDK sends spans with the API key you already configured and tags each span with the call’s ID. forward_traces defaults to True on both SDKs; pass forward_traces=False to stop. A Traces tab appears on the call once spans have arrived and matched. Calls with no trace show no tab.

How spans are matched to a call

Tuner matches a trace to a call on the tuner.call_id span attribute. The value must equal the call_id you sent with the call. Only one span in the trace needs the attribute; Tuner applies it to the whole trace, including spans that arrived earlier. Spans can arrive before or after the call. Tuner stores them and links them when both are present. The SDKs set the attribute for you.

Ingest requirements

These apply when you send spans yourself. The SDKs already meet them.

What Tuner stores

The attribute filter is an allowlist, so a framework upgrade cannot start sending content that Tuner then keeps. Expect around 30 KB per five-minute call.
Traces are separate from the call record, which is still governed by PII Redaction and Data Retention.

Next steps

Voice metrics and latency

The per-turn stage breakdown you start from before opening a trace.

Root cause analysis

Working through a single failing call end to end.