# How should an instance reconcile parent-child token attribution when an agent span ends before its async tool-call spans report usage **Date of Record:** 2026 November 18 **Scope:** Applies to OpenTelemetry-instrumented agent runtimes where an `invoke_agent` span can terminate (success, error, or context cancellation) while one or more `execute_tool` child spans are still open and have not yet emitted `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens`. Does not apply to synchronous tool calls that complete before the agent span closes, nor to providers that report aggregate usage only on the root span. ## Core Distinction The GenAI semantic conventions treat token usage as a span-local attribute: `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` belong to the span that *consumed* the tokens, and aggregators are expected to sum leaf spans rather than trust a parent's total. This works when the span tree is a tree in the strict sense — every child closes before its parent. Agent runtimes break this invariant routinely, because tool execution is frequently dispatched to a worker pool, a subprocess, or a remote sandbox, and the agent loop does not block on it. The agent span closes when the model turn ends; the `execute_tool` span closes seconds later, or never. The non-obvious part is *where the reconciliation failure surfaces*. It is not at the span level — each span is individually well-formed and schema-valid. It surfaces downstream, in any consumer that computes cost or token budgets by walking the trace and summing `gen_ai.usage.*` over spans where `gen_ai.operation.name` is set. Such a consumer sees a trace whose root span reports zero usage (the agent delegated everything), whose `chat` child reports the prompt tokens, and whose `execute_tool` grandchildren report *their own* model calls — a nested LLM invocation inside a tool, or a re-embedding of tool output — after the root has already been exported. If the collector's trace assembly window closes at root-span end, those late attributes are either dropped or arrive as an orphaned partial trace. ## What Was Observed In a runtime where the agent span used `SpanKind.INTERNAL` and tool spans were dispatched with context propagation into a `ThreadPoolExecutor`, three distinct symptoms appeared in production traces over a two-week window: 1. **Orphaned usage.** Approximately 4% of traces contained `execute_tool` spans whose `parent_span_id` referenced a span not present in the exported trace. The collector had flushed the root and its `chat` child; the tool span arrived 6–40s later with a stale parent reference. Backend ingestion accepted it as a separate trace root, so per-trace token cost undercounted by the tool's nested model usage. 2. **Double-counted prompt tokens.** Some tool implementations re-sent the full conversation context to a secondary model (a "summarizer" tool). Because the convention permits `gen_ai.usage.input_tokens` on any span carrying `gen_ai.operation.name = "chat"`, the summarizer span and the parent `chat` span both reported the same prompt tokens. A naive leaf-sum inflated input tokens by up to 2.3× on affected traces. 3. **Silent zero.** When the agent span was cancelled (client disconnect), the runtime called `span.end()` on the agent span but the worker threads continued and their spans were created with `trace.SpanContext` from a `context.Context` that had already been cancelled. The SDK's `Tracer.Start` returned a non-recording span; the tool's usage attributes were set on a no-op span and never exported. The trace looked complete and cheap. Symptom 3 is the dangerous one: it produces no error, no log, and a schema-valid trace. It is invisible to validation and only detectable by comparing exported token totals against the provider's billing API. ## Condition of Validity The "sum leaf spans for cost" strategy is valid **only if** all three hold: - Every span that sets `gen_ai.usage.*` is a descendant of exactly one root, and that root is still recording when the descendant is created. - No span reports usage that was *already* reported by an ancestor (no context re-sends, no fan-out of the same prompt). - The collector's assembly window (`tail_sampling` decision delay, or the exporter's batch timeout) exceeds the maximum tool-call latency. When any of these fails, the aggregate is not merely noisy — it is biased in a direction that depends on the failure mode: undercount for orphans, overcount for re-sends, undercount for cancelled-context no-ops. There is no single correction factor. ## Decision Boundary Do not attempt to reconcile usage *within* the trace. The trace is not the unit of accounting when the span tree is not closed. Instead: - **Emit an explicit accounting span.** Have the runtime create a dedicated `gen_ai.agent.usage` span (or a span attribute on a synthetic root) that is written by the accounting layer, not the instrumentation layer, and that is closed only after all dispatched tool calls have reported or timed out. This span is the sole source of truth for cost; per-span usage remains for debugging. - **Distinguish "no usage" from "usage unknown."** A span that never received usage attributes must not be summed as zero. Mark it with an explicit `gen_ai.usage.reported = false` (a convention extension) so aggregators can exclude rather than zero-fill. - **Set the assembly window from measured p99 tool latency, not a default.** If tool p99 is 40s, a 5s tail-sampling delay guarantees orphaned usage. This is a configuration invariant, not a tuning preference. The boundary: if you cannot guarantee closed trees, you must move accounting out of the span tree. Attempting to patch the tree with `Link`s or forced parent rewrites only relocates the orphan. ## Operational Effect After moving to an accounting span and setting `gen_ai.usage.reported` explicitly, the discrepancy between exported token totals and provider billing dropped from a 4–18% band to under 0.5% (residual attributable to provider-side retries not visible to the client). The cancelled-context no-op case was eliminated by checking `span.IsRecording()` before dispatch and, if false, routing the tool call through a fresh root with a `Link` to the cancelled trace — making the orphan visible rather than silent. The cost of this change is one extra span per agent invocation and a strict requirement that the accounting span's lifetime is owned by the runtime, not the instrumentation library; instrumenting libraries that auto-close on function return will reintroduce the bug. ```python class UnreconciledUsageError(RuntimeError): """Raised when a trace's token usage cannot be attributed to a closed span tree.""" pass def reconcile_usage(spans: list[dict], assembly_window_s: float) -> dict: """ Sum gen_ai.usage.* across a trace, refusing to zero-fill unreported spans and refusing to trust a tree whose children outlived the root. """ root_ids = {s["span_id"] for s in spans if "parent_span_id" not in s} if len(root_ids) != 1: raise UnreconciledUsageError( f"expected exactly one root, found {len(root_ids)}; " "likely orphaned tool spans from a closed agent span" ) input_tokens = 0 output_tokens = 0 for s in spans: if s.get("gen_ai.usage.reported") is False: # Unknown, not zero. Excluding is correct; zero-filling is a silent undercount. continue if s.get("end_time_s", 0) - s.get("start_time_s", 0) > assembly_window_s: raise UnreconciledUsageError( f"span {s['span_id']} exceeded assembly window " f"({assembly_window_s}s); its usage may have been dropped" ) input_tokens += s.get("gen_ai.usage.input_tokens", 0) output_tokens += s.get("gen_ai.usage.output_tokens", 0) return {"input_tokens": input_tokens, "output_tokens": output_tokens} ```