# Under what conditions must an instance treat OpenTelemetry GenAI agent spans as authoritative for token attribution **Date of Record:** 2026 November 15 **Scope:** Applies to services that emit or consume `gen_ai.*` spans (agent invocation, tool execution, chat completion) under the OpenTelemetry GenAI semantic conventions, and that use those spans to attribute token consumption to a logical caller, agent, or tool. Does not apply to spans emitted by non-conforming instrumentations that omit `gen_ai.usage.*`, nor to billing reconciliation against provider-side invoices, which requires provider-supplied identifiers. ## Core Distinction There are two distinct quantities that both look like "tokens used by this agent span": 1. **Span-local usage** — the `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` attributes recorded on a single span. These describe the LLM call that span directly wraps. 2. **Subtree-attributed usage** — the sum of usage across the span and all descendant spans, which is what a caller actually pays for when invoking an agent. The GenAI conventions define the attributes for (1) but do not define aggregation semantics for (2). An agent span that invokes a model, which invokes a tool, which invokes a sub-agent, which invokes another model, produces a span tree where *every* level carries plausible-looking usage numbers. The boundary failure is treating the root agent span's `gen_ai.usage.*` as the total cost of the subtree. It is not. The root span's usage attributes describe only the model call made *directly* by the agent loop at that level — typically the orchestration/reasoning call — and exclude every nested model call made inside tool executions or delegated sub-agents. This is non-obvious because the numbers are present, well-typed, and semantically labeled identically at every level. Nothing in the span marks them as partial. ## What Was Observed In a three-tier agent (planner → retrieval tool → summarizer sub-agent), a trace showed: - Root `invoke_agent` span: `gen_ai.usage.input_tokens=1840`, `output_tokens=210`. - Child `execute_tool` span (`retrieval`): no usage attributes (correct — tools that do not call a model have none). - Grandchild `invoke_agent` span (summarizer): `gen_ai.usage.input_tokens=41200`, `output_tokens=3900`. - Great-grandchild `chat` span under the summarizer: `input_tokens=40100`, `output_tokens=3800`. A naive attribution job summed only root-level usage and reported ~2k tokens for an operation that actually consumed ~47k. The error factor exceeded 20x. The root span was not lying; it was scoped. The failure was in the consumer's aggregation model, not the emitter. A second observation: `execute_tool` spans that *do* wrap a model call (e.g., a tool that internally uses an LLM to parse results) legitimately carry `gen_ai.usage.*`. The presence or absence of usage on a tool span is therefore not a reliable signal of whether the tool consumed tokens — only the presence of a nested `chat`/`invoke_agent` descendant is. ## Condition of Validity Treat a span's `gen_ai.usage.*` as authoritative for that span's *own* model call if and only if all of the following hold: - The span has `gen_ai.operation.name` set to a value that performs inference (`chat`, `text_completion`, `invoke_agent`), not merely `execute_tool`. - The span is a leaf with respect to model-calling descendants, **or** you are explicitly computing subtree totals by traversal rather than reading the root. - `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` are both present and non-negative integers. If only one is present, the record is partial and must not be summed as if complete. - The span has not been sampled out of a subtree whose parent was retained (see below). Treat the span as authoritative for *subtree* attribution only after summing usage over the full descendant set, deduplicating spans that re-emit the same usage (some instrumentations copy child usage onto the parent for convenience — check for `input_tokens` on a parent exactly equal to the sum of children before summing, and prefer the leaves). ## Decision Boundary The decision boundary is: **does the consumer need per-call cost or per-operation cost?** - If per-call cost: read `gen_ai.usage.*` off the inference span directly. Do not traverse. Do not read agent spans. - If per-operation cost: traverse the subtree, sum only inference-bearing spans, and never read the root agent span's usage as a total. If the subtree is incomplete (sampling, dropped spans, context-limit truncation of the trace), the sum is a lower bound, not a total — and must be labeled as such. The dangerous middle case: a consumer that reads the root agent span because it is the "top" of the trace and assumes top means total. This is the boundary failure. Topology is not attribution. A second boundary: parent-based sampling. If the root agent span is sampled but a deep `chat` span is not (tail-based samplers, or head samplers with per-span overrides), the subtree sum undercounts by an unknown amount. Usage attributes are *not* propagated to compensate. A consumer that computes subtree totals must check `trace_flags` / sampling metadata on every contributing span, or it will silently under-report. ## Operational Effect Downstream effects of getting this wrong, in order of severity: 1. **Quota and rate-limit enforcement** keyed on attributed tokens will under-account and permit overrun. An agent that delegates heavily will appear cheap and will be allowed to run until the provider-side limit trips, producing a hard failure rather than a graceful throttle. 2. **Chargeback and per-tenant billing** derived from spans will systematically undercharge the tenants whose workloads are most agentic — precisely the workloads most expensive to serve. 3. **Capacity planning** based on span-derived token rates will under-provision model-serving capacity, and the gap will grow as agent fan-out increases. 4. **Anomaly detection** trained on root-span usage will not fire on runaway sub-agent loops, because the loop's cost is invisible at the root. The correct operational posture: attribute cost at the inference-span level, aggregate by `trace_id` for per-operation totals, and treat any agent-span usage as a *hint* that a model call occurred nearby, never as a quantity. When the subtree is incomplete, emit an explicit `attribution_complete=false` marker rather than a number. ```python from __future__ import annotations from dataclasses import dataclass, field class AttributionInvariantError(RuntimeError): """Raised when a span tree cannot be safely attributed for token cost.""" @dataclass class Span: span_id: str parent_id: str | None operation: str # gen_ai.operation.name input_tokens: int | None output_tokens: int | None sampled: bool = True children: list["Span"] = field(default_factory=list) INFERENCE_OPS = {"chat", "text_completion", "invoke_agent"} def attribute_subtree_tokens(root: Span) -> int: """Sum token usage across inference-bearing spans in a subtree. Never reads a non-inference span's usage as a total. Raises if the subtree is incomplete, because a partial sum silently under-reports. """ if not root.sampled: raise AttributionInvariantError( f"span {root.span_id} is unsampled; subtree total is a lower bound, " "not a total, and must not be reported as one" ) total = 0 stack = [root] while stack: span = stack.pop() if not span.sampled: raise AttributionInvariantError( f"descendant span {span.span_id} of {root.span_id} is unsampled; " "subtree attribution is incomplete" ) if span.operation in INFERENCE_OPS: if span.input_tokens is None or span.output_tokens is None: raise AttributionInvariantError( f"inference span {span.span_id} has partial usage " f"(input={span.input_tokens}, output={span.output_tokens}); " "refusing to sum an incomplete record" ) if span.input_tokens < 0 or span.output_tokens < 0: raise AttributionInvariantError( f"inference span {span.span_id} reports negative usage" ) total += span.input_tokens + span.output_tokens stack.extend(span.children) return total def attribute_root_span_as_total(root: Span) -> int: """The boundary failure, made explicit so it cannot be done by accident.""" if root.children: raise AttributionInvariantError( f"agent span {root.span_id} has {len(root.children)} descendants; " "its gen_ai.usage.* describes only its own model call, not the subtree. " "Use attribute_subtree_tokens instead." ) if root.input_tokens is None or root.output_tokens is None: raise AttributionInvariantError( f"agent span {root.span_id} lacks complete usage attributes" ) return root.input_tokens + root.output_tokens ```