Evalgent
Back to Blog
Voice AI Testing

OpenTelemetry Trace and Span Model for Voice Agents: ASR, LLM, Tools and TTS

Deepesh Jayal
16 min read
OpenTelemetry Trace and Span Model for Voice Agents: ASR, LLM, Tools and TTS
On this page

A voice agent is a pipeline that runs in real time, and its failures hide in the gaps between stages. Tracing makes those gaps visible, but only if every team's spans mean the same thing from call to call. This post is the schema reference. It proposes one span tree for an OpenTelemetry voice agent, defines what each span's start and end should mean, and flags where voice breaks tracing assumptions. Think of it as a trace structure voice agent teams can copy and adapt.

Our earlier guide to OpenTelemetry for voice agents covers why tracing matters, the collector, and the basic hierarchy. Here we go deeper: span boundaries, overlap, interruptions and streaming. For the logging side, see what to log on every voice agent call. For the wider picture, see the voice agent observability checklist.

Evalgent Observe, which is launching, ingests client data in OpenTelemetry format from any stack. It never sits in the media path, so nothing touches live audio or slows a call. That makes the quality of your spans the limit on how well a failed call can be explained. Everything below is a recommendation for your own instrumentation. You do not need to match it to use Observe, and the same data works with any OTLP backend, which is the point of otel voice ai work.

The OpenTelemetry concepts you need, in voice terms

You need seven ideas about trace and span design. All definitions below come from the OpenTelemetry traces documentation and the trace API specification.

Trace: the path of a request through a system. It is a collection of related spans linked by a shared trace ID and parent-child relationships. For us, one trace is one phone call.

Span: a single unit of work, and the building block of a trace. A span carries a name, a parent span ID (empty for the root), start and end timestamps, a span context, attributes, events, links and a status. In a voice trace, a span is one stage of a turn, such as one STT utterance or one TTS playback.

Attributes: key-value metadata on a span. Values must be strings, booleans, floats, integers or arrays of those. The documentation advises adding attributes at span creation where possible, because SDK sampling can only use what exists then.

Span events: a timestamped annotation inside a span. The documentation gives a simple test. If the timestamp matters, use an event. If it does not, use an attribute. Voice leans on this rule heavily, as we will see.

Span links: a causal association between spans that are not parent and child. They suit work that starts asynchronously. Links are optional.

Span status: one of Unset, Error or Ok. Unset is the default and means the operation completed without an error. Ok is an explicit developer mark, and the spec says it should be final once set.

Span kind: Internal, Client, Server, Producer or Consumer. Internal is the default. Client describes a request to a remote service where the caller waits for a response. A call from your agent to a hosted STT, LLM or TTS provider fits Client. Treat it as a judgment call for streaming connections, since the spec's wording is about a request awaiting a response.

Two more rules matter for what follows. First, the spec says every created span must be ended. Second, ending a span has no effect on its children, and an ended span can still be a parent. A child may legitimately outlive its parent. We use that fact later.

The tree below is our recommended OpenTelemetry trace span model voice agents can adopt. It is a design suggestion, not an OpenTelemetry standard and not an Evalgent requirement. The span names are ours. OpenTelemetry has no voice conventions, so you are free to choose, and consistency across your own services is what counts.

voice.call                          one per phone call (root span)
  voice.connection                  telephony / transport setup
  voice.turn  (index 1)             caller speech onset -> end of agent playback
    voice.stt                       caller audio -> final transcript
    voice.llm                       model request -> last token
      voice.tool                    one per tool call the model requested
    voice.tts                       synthesis request -> end of playback
  voice.turn  (index 2)
    voice.stt
    voice.llm
    voice.tts
  voice.turn  (index 3)
    ...
Waterfall of one voice turn with STT, LLM, tool and TTS spans, showing the TTS span starting before the LLM span ends. Timings are illustrative, not measured.

These voice agent spans follow a simple logic:

  • One trace per call. Every turn sits under one root, so you can open a call and read it top to bottom. The trade-off is a long-lived root span. We cover that under the pitfalls below.
  • Turns as the unit of analysis. Almost every voice complaint is about a specific exchange: the agent was slow, talked over me, or missed what I said. A turn span gives each complaint a place to live.
  • Stages as children. STT, LLM and TTS are the three service calls in a cascading pipeline. Each gets its own span so the duration of each stage is a number you can read.
  • Tools under the LLM span. The model requests a tool, so the tool span nests under the model call that asked for it. You can then see which output led to which action.
  • Connection as a sibling. Call setup belongs to no turn, so it gets its own span under the root.

If your agent is speech-to-speech, there are no separate STT, LLM and TTS stages to wrap. We cover that case below.

What each span should start on and end on

Most broken voice traces are broken by vague boundaries, not missing spans. If one service starts its STT span when audio arrives and another starts it when the first partial transcript arrives, the numbers cannot be compared. Write the definitions down once. The table is our suggested set.

SpanStarts whenEnds whenWorth recording
voice.callThe call is answered, or dialing begins for outboundThe session is torn down, in a finally pathCall ID, agent and prompt version, direction, how the call ended
voice.connectionDial or offer is initiatedFirst media is flowing, or setup failsTransport type, setup outcome, a failure reason if any
voice.turnCaller speech onset is detected, or the agent starts an agent-initiated turnAgent playback ends, or the caller cuts it offTurn index, whether it was interrupted, whether it errored
voice.sttFirst audio of the utterance is sent to the recognizerFinal transcript is receivedProvider, model, language, transcript length (not the text)
voice.llmThe model request is sentThe last token arrives or the stream closesModel, token counts, finish reason
voice.toolThe tool call is dispatchedThe result or timeout is returnedTool name, outcome category, retry count
voice.ttsThe synthesis request is sentPlayback ends, or is cut shortProvider, voice, whether playback was cut short

Three details in that table deserve a note.

The turn starts before anyone knows it is a turn. You detect speech onset slightly after it happens. The OpenTelemetry spec anticipates this: a start timestamp "SHOULD only be set when span creation time has already passed." So create the turn span after the fact, and pass the real onset time.

Pick one meaning for the end of TTS. Synthesis can finish long before the caller hears the last word, because audio is buffered and played at real-time speed. If you can observe playback, end the span at playback end. If you cannot, end it at the last synthesized chunk and say so in your docs. Mixing the two across services corrupts every duration comparison.

Record lengths, not text. Transcripts and tool arguments often contain personal data. Recording a length or a category answers most debugging questions. Handle content in your collector or a separate store.

Where voice breaks the usual tracing assumptions

Most OpenTelemetry guidance comes from request-response systems, where work nests neatly. Voice is a duplex, streaming system, so any OpenTelemetry trace span model voice agents use must handle five differences.

Stages overlap

In a streaming pipeline, TTS starts speaking the first sentence while the LLM is still generating the rest. STT may still be finalizing while the model has begun. If you nest TTS inside LLM, you imply TTS cannot outlive the model call, and the picture lies. Make them siblings under the turn. The timeline then shows the real overlap, which is exactly the thing you want to see.

The spec allows a child to outlive its parent, but you rarely want that here. Keep every stage span inside the turn's time range. A stage that runs past the turn end is a signal to investigate.

Interruptions cut spans short

A caller can speak while the agent is talking. This is called barge-in. The agent should stop playback, drop the rest of the response, and start a new turn. Think about what each span should do:

  • The TTS span ends at the moment playback stops. Add an interruption event with the cut-off time.
  • The turn span ends at the same moment and carries an attribute marking it interrupted.
  • An LLM span that is still streaming gets ended when you cancel it. Mark it cancelled with an attribute.
  • A tool span in flight is the dangerous one. The tool may still complete on the other side. Our post on interrupted tool calls explains the retry and duplicate risk.

Do not set Error status for a barge-in. The spec says Unset means the operation completed without an error, and an interruption is normal conversation. Reserve Error for real failures, or the "errored traces" filter fills with noise. The interruption itself is a timestamped moment, so it is an event, by the documentation's own rule.

Timeline of an interrupted turn: the TTS span and turn span end at the barge-in time, with an interruption event on the TTS span. Timings are illustrative.

For evaluating interruptions themselves, see interruption detection evaluation. For one cause of false barge-ins, see self-interruption and echo.

Streaming creates moments, not durations

Time to first token and time to first audio are points inside a longer span. Our post on time to first audio explains why they drive perceived responsiveness. In trace terms, they are events: first partial transcript on the STT span, first token on the LLM span, first audio chunk on the TTS span. The timestamp is the whole point, so an event fits better than a pre-computed attribute. A trace backend can then derive any interval from raw timestamps, and you can change the definition later without re-instrumenting.

Do not emit an event per audio frame. The spec's default limit is 128 events per span, and SDKs may discard events beyond it.

Silence has no span

Between turns, nobody is speaking. Do not create a span for silence. The gap between the end of one turn and the start of the next is visible in the timeline as empty space under the call span. That empty space is data. A long gap with no span running is where you look for dead air, and it only shows up if you resist filling it with placeholder spans. The latency post lists the clocks you can derive from these gaps.

Speech-to-speech agents have no stage boundaries

A speech-to-speech model takes audio in and returns audio out in one session. There is no separate STT, LLM and TTS to wrap. For this architecture, we suggest a single model-session span per turn, with events for the moments you can observe: input speech detected, first output audio, interruption, and any tool request. You lose stage-level durations, and you should say that plainly in your telemetry docs. Our guide to testing speech-to-speech voice agents covers what remains observable from outside.

New instrumentation often goes wrong by picking the wrong feature. The rules below follow the OpenTelemetry definitions.

Decision grid: child span for work with a duration, event for a timestamped moment, attribute for a fact about a span, link for a causal relation outside the parent tree.
  • Child span when the work has its own duration and might fail on its own. STT, LLM, tool and TTS qualify.
  • Event when a moment inside a span matters by time. First token, first audio, interruption, endpoint detected.
  • Attribute when the fact is a property of the whole span. Model name, language, outcome category.
  • Link when two spans are causally related but not parent and child. A tool that kicks off a webhook completed minutes later is a good case. So is post-call processing started by the call ending: link its span back to the call's span context.

One more rule from the spec: prefer setting links and attributes at span creation, because sampling decisions only see what is present at that point.

Naming spans and attributes

The spec says a span name should be "the most general string that identifies a (statistically) interesting class of spans," and that generality should beat human readability. Its example prefers get_account over get_account/42. Apply that here. Name the span voice.turn and put the turn index in an attribute. Never name it voice.turn.7. High-cardinality names break grouping in every backend.

For attributes, reuse standard names where they exist and use a clear prefix for your own. Semantic conventions exist to give common data shared names across codebases and tools, per the semantic conventions overview. Mixing your own keys into a standard namespace invites clashes later.

Do the GenAI semantic conventions cover voice?

Partly. As of November 19, 2026, the GenAI conventions have moved to their own semantic-conventions-genai repository. The old attribute registry page now points there. On the registry page, the well-known gen_ai.operation.name values include chat, execute_tool and invoke_agent, all marked development stability. Attributes such as gen_ai.conversation.id, gen_ai.tool.name and gen_ai.request.model exist in the attribute registry.

What we did not find is any voice-specific span or attribute for transcription, endpointing, barge-in or playback. The only speech-related item on the registry page is a speech value for the output type attribute. So the pattern is: use the GenAI names for your LLM and tool spans if your backend reads them, and use your own prefixed names for the audio stages. Check the repository for changes before you pin anything, because the status is still development. Our earlier OpenTelemetry guide walks through the GenAI conventions in more depth.

How to instrument one voice turn in five steps

The sample is simplified and generic. It uses only the OpenTelemetry Python API: get_tracer, start_span, set_span_in_context, add_event, set_attribute, set_status and end. The signatures come from the Python API reference. Configure the SDK and an exporter separately, as in the Python instrumentation guide. The timestamps are integers you capture yourself. The OTLP field names end in UnixNano, which suggests nanoseconds since the epoch, so we use time.time_ns(). Confirm the unit for your SDK version.

1. Open the call span without a context manager — Use start_span, not start_as_current_span. A call outlives any single function, so you hold the span and end it yourself in a finally path. Put the returned span into a context with set_span_in_context.

2. Create the turn span with the real start time — When your voice activity detector reports speech onset, create voice.turn with start_time set to the onset timestamp you captured. Pass the call context as the parent.

3. Open stage spans as siblings — Create STT, LLM and TTS spans under the turn context, each with the start time defined in the table above. Do not nest TTS under the LLM span. Set kind to Client for provider calls.

4. Add events for moments, attributes for facts — Use add_event with an explicit timestamp for first partial, first token, first audio and interruption. Use attributes for model, provider and outcome category.

5. End every span with its real end time — Call end(end_time=...) on each span. On barge-in, end TTS and the turn at the cut-off time. Set Error status only for genuine failures, such as a tool timeout.

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode, SpanKind

tracer = trace.get_tracer("voice-agent")

def start_call(call_id):
    call = tracer.start_span("voice.call", attributes={"voice.call.id": call_id})
    return call, trace.set_span_in_context(call)

def trace_turn(call_ctx, index, t, barge_in_ns=None):
    # t: nanosecond timestamps captured with time.time_ns()
    turn = tracer.start_span("voice.turn", context=call_ctx,
                             start_time=t["speech_start"],
                             attributes={"voice.turn.index": index})
    ctx = trace.set_span_in_context(turn)

    stt = tracer.start_span("voice.stt", context=ctx, kind=SpanKind.CLIENT,
                            start_time=t["speech_start"])
    stt.add_event("voice.stt.first_partial", timestamp=t["first_partial"])
    stt.end(end_time=t["final_transcript"])

    llm = tracer.start_span("voice.llm", context=ctx, kind=SpanKind.CLIENT,
                            start_time=t["llm_request"])
    llm.add_event("voice.llm.first_token", timestamp=t["first_token"])

    # TTS starts while the LLM is still streaming: a sibling, not a child.
    tts = tracer.start_span("voice.tts", context=ctx, kind=SpanKind.CLIENT,
                            start_time=t["tts_request"])
    tts.add_event("voice.tts.first_audio", timestamp=t["first_audio"])
    llm.end(end_time=t["llm_done"])

    if barge_in_ns is None:
        tts.end(end_time=t["playback_end"])
        turn.end(end_time=t["playback_end"])
    else:
        tts.add_event("voice.interruption", timestamp=barge_in_ns)
        tts.set_attribute("voice.playback.cut_short", True)
        tts.end(end_time=barge_in_ns)          # not an error
        turn.set_attribute("voice.turn.interrupted", True)
        turn.end(end_time=barge_in_ns)

A real agent often has a framework that creates most of these spans for you. Use the sample to check that the framework's spans match your definitions. For a failed tool span, set Status(StatusCode.ERROR, "timeout") and end it with the real result time.

Common mistakes in voice span models

  • Nesting everything. Putting TTS under LLM under STT because "that is the order things happen" hides overlap, which is the most useful thing a voice trace shows.
  • Never ending the root. The spec says every span must be ended. A crash path that skips end leaves the call span unfinished. Put it in finally.
  • Ignoring long roots. A call span can last many minutes. Test your collector and backend with your longest realistic call.
  • Sampling away the failures. Head sampling decides before the trace is complete, so it cannot select by error or latency. Only tail sampling can, per the OpenTelemetry sampling guide. See also how to sample live calls.

How a consistent span model helps debugging

A trace shows what each step did and when. It does not decide on its own which step caused a failure. That takes a consistent structure, so the same span means the same thing on every call. Evalgent Observe traces each failure to the step or handoff that caused it, and groups failures into root causes so a team fixes causes, not single calls. It gives no verdict without evidence in the data you send. Where the data is blind, it says "undetermined" and shows the coverage gap. A missing stage span is exactly that kind of gap, and a clear model makes it obvious.

For how tracing sits beside testing and monitoring, see testing vs monitoring vs observability and monitoring AI voice agents in production.

Frequently asked questions

What is a span in OpenTelemetry?

A span is a single unit of work and the building block of a trace. It has a name, a parent span ID, start and end timestamps, a span context, attributes, events, links and a status. In a voice agent, one span might cover one speech-to-text utterance, one model call, one tool call or one stretch of speech playback.

How should you structure spans for a voice agent?

Use one trace per call. Put a call span at the root, a connection span for setup, and one turn span per exchange. Under each turn, add child spans for speech-to-text, the LLM, any tool calls and text-to-speech. Define what starts and ends each span, and make streaming stages siblings so their overlap stays visible.

Should each turn be its own trace or a span inside a call trace?

One trace per call is our recommendation, because you can read the whole conversation in one place. The cost is a long-lived root span. If your backend struggles with that, use one trace per turn and share a call ID attribute. Either way, pick one and apply it consistently across services.

How do you represent an interruption in OpenTelemetry?

Add an event to the TTS span at the barge-in time, end the TTS span and turn span at that moment, and mark the turn as interrupted with an attribute. Do not set Error status. An interruption is normal conversation, and the Unset status means the operation completed without an error.

Do the OpenTelemetry GenAI semantic conventions cover voice?

Not for the audio stages. As of November 19, 2026, the conventions cover areas such as chat operations and tool execution, and they are marked development stability. We found no voice-specific attributes for transcription, endpointing or playback, so use your own clearly prefixed names for those spans.

Should first token and first audio be events or attributes?

Events. The documentation says to use an event when the timestamp matters and an attribute when it does not. First token and first audio are moments inside a longer span, so the timestamp is the point. A backend can derive any interval from raw timestamps later.

How do you trace a speech-to-speech voice agent?

There are no separate STT, LLM and TTS stages, so use one model-session span per turn. Add events for observable moments such as input speech detected, first output audio, interruption and tool request. Stage-level durations are unavailable, and your documentation should say so plainly.

Should transcripts go in span attributes?

Usually not. Transcripts and tool arguments often contain personal data, and span attributes are widely exported and retained. Record lengths and outcome categories on spans. Keep content in a separate, access-controlled store or apply redaction in your collector before export.

The bottom line

A good OpenTelemetry trace span model voice agents can rely on has one trace per call, one span per turn, and sibling stage spans whose start and end you have defined in writing. Make interruptions events, make silence visible as a gap, and keep Error status for real failures.

Related Articles