# What structural signals indicate a token-accounting divergence between OpenTelemetry GenAI agent spans and their child tool-call spans **Date of Record:** 2026 November 17 **Scope:** Applies to agentic workloads instrumented with OpenTelemetry GenAI semantic conventions (span kinds `chat`, `execute_tool`, and agent orchestration spans) where token usage is aggregated from child spans and compared against parent span attributes. Does not apply to single-turn LLM calls without tool invocation, nor to providers that emit usage only at stream finalization without per-span attribution. ## Core Distinction The GenAI semantic conventions define `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` as attributes of a model-invocation span. They do **not** define an aggregation contract across an agent tree. The non-obvious invariant is this: **a parent agent span's token attributes are not the sum of its children's token attributes when the agent performs multi-step reasoning, because each tool-call round-trip re-invokes the model and the accumulated context is re-billed on every invocation.** Observers routinely treat `parent.input_tokens ≈ Σ child.input_tokens` as a conservation law. It is not a conservation law; it is a coincidence that holds only for single-invocation agents. The structural signal is therefore not "do the numbers match" but "does the tree shape admit aggregation at all." A tool-call child span (`gen_ai.operation.name = execute_tool`) carries **no** token usage of its own — tool execution consumes no model tokens. Token usage lives on the *model invocation* spans that bracket the tool call. When instrumentation flattens the agent loop into a single parent span with `execute_tool` children, the parent's token count reflects N invocations while the children reflect zero, and any downstream accounting that sums children silently reports zero tokens for a run that actually billed N full context windows. ## What Was Observed In a replayed agent trace (12 tool calls, one model per step), the exported shape was: - Parent span `invoke_agent`: `gen_ai.usage.input_tokens = 184,320`, `output_tokens = 4,110`. - 12 child spans `execute_tool`: each with `gen_ai.tool.name`, `gen_ai.tool.call.id`, and **no** usage attributes. - Zero intermediate `chat` spans — the instrumentation collapsed the per-step model calls into the parent. A cost pipeline that summed `input_tokens` over all spans in the trace reported 184,320 for the run — correct by accident here because it read the parent. A second pipeline that summed only leaf spans reported 0. A third that summed *all* spans and deduplicated by `trace_id` double-counted when the SDK emitted both a `chat` span and its enclosing `invoke_agent` span with identical usage. Three pipelines, three answers, one ground-truth bill. The tell was structural, not numeric: the ratio of `execute_tool` children to `chat` spans was 12:0. A well-formed agent trace has a `chat` span per tool round-trip. The absence of `chat` spans between tool calls is the divergence signal — the token accounting has been hoisted to a span that no longer represents a single invocation. ## Condition of Validity Aggregation of child token attributes to a parent is valid **only** when every model invocation is represented by exactly one span and that span is a descendant of the agent span, with no invocation represented at two levels of the tree. This requires: 1. One `chat` (or `gen_ai.operation.name = chat`) span per model call, including calls that precede and follow tool execution. 2. `execute_tool` spans carrying no usage attributes (they must not, since they consume no tokens). 3. No span that both owns usage and has descendants that also own the same usage (no double-attribution across levels). When instrumentation hoists usage to the agent span and omits per-invocation `chat` spans, condition 1 fails and the aggregation contract is void. The parent value is still *correct as a total* but is no longer *decomposable*, and any consumer that assumes decomposability will mis-account. ## Decision Boundary The operational rule: **before summing token attributes across a trace, assert that the count of model-invocation spans equals the count of tool-call spans plus one (the terminal response).** If `chat_span_count < tool_call_count`, the trace has hoisted accounting and must be read from the agent span only, never from a child sum. If `chat_span_count == tool_call_count + 1`, per-invocation aggregation is safe and should reconcile to the parent within a tolerance for cached-token accounting, which the conventions report separately (`gen_ai.usage.cache_read.input_tokens`) and which must be excluded from naive sums or it will overstate billable input. A second boundary: streaming responses that finalize usage after the span ends. If `output_tokens` is absent on a `chat` span but present on the parent, the child span closed before usage was known. Treat missing usage on a `chat` span as "unknown," not "zero," and refuse to aggregate. ## Operational Effect The practical consequence is that cost attribution and per-agent budget enforcement cannot share one aggregation path. Budget enforcement must read the agent span (the billed total). Per-tool cost attribution must read `chat` spans and will fail closed when the instrumentation hoists. The correct posture is to detect the hoisted shape at ingest and route the trace to a single-span accounting path rather than a tree-sum path, and to alert on `chat_span_count < tool_call_count` because it means the trace is structurally un-attributable for any per-step analysis — a condition that silently zeroes per-tool cost dashboards while the invoice stays correct. ```python class TokenAggregationInvariantError(RuntimeError): """Raised when a trace's span shape cannot support per-invocation token aggregation.""" pass def reconcile_token_usage(spans: list[dict]) -> dict: """ spans: exported OTel spans for one trace, each a dict with 'name', 'operation' ('chat' | 'execute_tool' | 'invoke_agent'), and optional 'input_tokens' / 'output_tokens'. Returns a reconciled accounting dict or raises if the shape is un-attributable. """ chat = [s for s in spans if s.get("operation") == "chat"] tools = [s for s in spans if s.get("operation") == "execute_tool"] agents = [s for s in spans if s.get("operation") == "invoke_agent"] if not agents: raise TokenAggregationInvariantError( "no invoke_agent span: cannot establish billed total" ) # Structural signal: a well-formed agent trace has one chat span per # tool round-trip plus a terminal response. if len(chat) < len(tools): raise TokenAggregationInvariantError( f"hoisted accounting detected: {len(chat)} chat spans for " f"{len(tools)} tool calls; per-invocation aggregation is void. " f"Read totals from invoke_agent span only." ) # Missing usage on a chat span means 'unknown', not 'zero'. for s in chat: if "input_tokens" not in s or "output_tokens" not in s: raise TokenAggregationInvariantError( f"chat span {s.get('name')!r} closed before usage finalized; " f"refusing to aggregate unknown as zero" ) # Cache reads are reported separately and must not inflate billable input. per_invocation_input = sum( s["input_tokens"] - s.get("cache_read_input_tokens", 0) for s in chat ) per_invocation_output = sum(s["output_tokens"] for s in chat) agent_total_input = sum(a.get("input_tokens", 0) for a in agents) agent_total_output = sum(a.get("output_tokens", 0) for a in agents) return { "billed_input": agent_total_input, "billed_output": agent_total_output, "attributed_input": per_invocation_input, "attributed_output": per_invocation_output, "decomposable": True, } ```