# What happens when an instance emits a single GenAI span for a multi-turn tool-calling exchange: token accounting and parent-context divergence at the OpenTelemetry GenAI semantic convention boundary **Date of Record:** 2026 November 15 **Scope:** Applies to services instrumenting LLM calls, tool invocations, and agent-to-agent handoffs under the OpenTelemetry GenAI semantic conventions (`gen_ai.*`), specifically when one logical request triggers more than one model call or tool round-trip. Does not apply to single-shot completions with no tool calls, nor to pure infrastructure spans (`http.*`, `rpc.*`) that carry no `gen_ai.*` attributes. ## Core Distinction The GenAI semantic conventions model a *chat inference operation* (`gen_ai.operation.name = chat`) as a leaf span whose `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` describe **one** model round-trip. A *tool call* is modeled as either an `execute_tool` span or an event/attribute on the parent chat span. A *multi-agent handoff* is modeled as a span link or a new trace rooted at the callee. The boundary failure: when an implementation collapses an entire tool-calling loop — model call → tool execution → model call → final answer — into **one** `chat` span, the span is structurally valid (passes schema validation, has the required attributes) but is semantically corrupt. Its token counters become a sum across N round-trips while its `gen_ai.request.model` names a single model, and its `trace_id`/`parent_span_id` become the sole propagation anchor for tool work that logically occurred *after* the first model response. Downstream cost attribution, latency decomposition, and causal reconstruction all silently break — no error is raised, because no invariant in the schema forbids it. ## What Was Observed A tool-orchestrating agent (three sequential tool calls, four model round-trips) was instrumented with a single wrapping `chat` span. Observed consequences: - **Token double-counting under fan-out.** `gen_ai.usage.input_tokens` was recorded as the sum of all four requests. A cost dashboard that multiplied `input_tokens × price` per span attributed the full loop cost to the *first* model's price tier, overstating spend by ~2.3× because later rounds used a cheaper model. The span's `gen_ai.request.model` was a single string; there is no field to express "four requests across two models." - **Orphaned tool spans.** `execute_tool` child spans were parented to the single chat span, so their start times fell *after* the chat span's recorded `gen_ai.response.finish_reasons` of `tool_calls` — a finish reason that semantically terminates a turn. Trace viewers rendered tool spans as children of a span that had already "finished," producing impossible causation in waterfall views. - **Broken multi-agent propagation.** When the loop delegated to a sub-agent, the sub-agent's trace was linked to the *outer* chat span rather than the specific round-trip that triggered it. A retry of round 3 could not be distinguished from the original round 3 because both shared the same parent and no round index existed. Sampling decisions made at the outer span propagated to all rounds uniformly, so a tail-sampling policy that would have kept the failing round dropped it as part of a "successful" aggregate. The critical non-obvious point: **the span passed every validator.** `gen_ai.system`, `gen_ai.operation.name`, `gen_ai.request.model`, and token attributes were all present and well-typed. The corruption was purely relational and temporal. ## Condition of Validity The one-span-per-loop model is only valid when **all** of the following hold: 1. Exactly one model round-trip occurs (no tool calls, or tool calls executed outside the span's temporal bounds). 2. All token usage is attributable to a single `gen_ai.request.model` and a single `gen_ai.response.model`. 3. No child span is emitted whose `start_time` exceeds the parent chat span's `end_time` minus its own duration (i.e., no post-finish-reason work is nested). 4. Multi-agent delegation, if any, carries an explicit span link to the originating round, not merely to the aggregate. If any condition fails, the span must be decomposed: one `chat` span per round-trip, each with its own token counters, chained via parent-child or `gen_ai.conversation.id`, and tool spans parented to the round that requested them. ## Decision Boundary Emit a **single** `chat` span only for atomic, single-round inference. Emit a **span per round-trip** (plus `execute_tool` children) whenever `finish_reason == tool_calls` triggers further work, or whenever the loop crosses model boundaries, or whenever a sub-agent is invoked. The decision hinges on whether the span's token counters can be honestly attributed to one model and one temporal window — if not, the span is a lie that the schema permits. ## Operational Effect Correct decomposition restores: per-round cost attribution, valid latency decomposition (time-to-first-token vs. tool execution vs. subsequent rounds), stable parent context for retries and sampling, and reconstructable causality for multi-agent traces. The cost is span cardinality — a 4-round loop yields 4 chat spans + 3 tool spans instead of 1 — which is the correct price for a trace that can be trusted. Aggregate metrics should be computed by summing over `gen_ai.conversation.id`, never by reading a single collapsed span. ```python from dataclasses import dataclass, field from typing import Optional class GenAISpanModelingError(RuntimeError): """Raised when a GenAI span collapses multiple round-trips or violates temporal/parent invariants.""" pass @dataclass class GenAISpan: operation: str # e.g. "chat", "execute_tool" model: Optional[str] input_tokens: int output_tokens: int finish_reason: Optional[str] start_time: float end_time: float round_index: Optional[int] = None parent_round: Optional[int] = None child_spans: list = field(default_factory=list) def validate_chat_span(span: GenAISpan, round_trips: int, models: set) -> None: if span.operation != "chat": return # Invariant 1: token counters must describe exactly one round-trip. if round_trips > 1: raise GenAISpanModelingError( f"chat span aggregates {round_trips} round-trips; token counters " f"({span.input_tokens}/{span.output_tokens}) are not attributable to one request. " "Decompose into one chat span per round-trip." ) # Invariant 2: a single span cannot honestly name multiple models. if len(models) > 1: raise GenAISpanModelingError( f"chat span names one model but {len(models)} models participated: {sorted(models)}" ) # Invariant 3: no child work may begin after a terminal finish_reason. if span.finish_reason in ("tool_calls", "stop"): for child in span.child_spans: if child.start_time >= span.end_time: raise GenAISpanModelingError( f"child span {child.operation!r} starts at {child.start_time} " f">= parent end_time {span.end_time} after finish_reason={span.finish_reason!r}; " "tool work was nested under a finished turn." ) # Invariant 4: multi-agent delegation must link to a specific round. if span.child_spans and span.round_index is None: raise GenAISpanModelingError( "aggregate chat span has children but no round_index; " "sub-agent links cannot be resolved to a specific round-trip." ) ```