# What structural signals indicate a token-accounting invariant violation at the OpenTelemetry GenAI agent-span boundary **Date of Record:** 2026 November 15 **Scope:** Applies to OpenTelemetry GenAI semantic conventions (`gen_ai.*`) for agent and tool spans where `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` are emitted per span and reconciled against a parent agent invocation. Does not apply to raw provider SDK billing reconciliation or to spans that emit only `gen_ai.usage.total_tokens` without the input/output split. ## Core Distinction The non-obvious boundary is between *sum-of-child token attributes* and *parent agent-span token attributes*. The GenAI conventions treat `gen_ai.usage.*` as attributes of the span that made the model call. When an agent span wraps multiple LLM calls (a ReAct loop, a planner, a multi-step tool chain), the natural implementation is to aggregate child `gen_ai.usage.*` into the parent. That aggregation is where the invariant silently breaks: the parent's `gen_ai.usage.input_tokens` becomes a *derived* quantity that no longer satisfies the per-call contract, yet it is indistinguishable in shape from a genuine single-call measurement. The failure is not that numbers are wrong. It is that the *provenance* of the number changed (measured → synthesized) while the attribute key stayed identical. Downstream consumers — cost dashboards, context-window guards, rate-limit estimators — assume the attribute is a measurement. ## What Was Observed In a multi-tool agent trace, the following structural signals co-occurred and were diagnostic: 1. **Cardinality mismatch between `gen_ai.operation.name` and usage presence.** The parent span carried `gen_ai.operation.name = "invoke_agent"` *and* `gen_ai.usage.input_tokens`, while also having N child spans with `gen_ai.operation.name = "chat"` that each carried their own usage. Per the conventions, usage belongs to the span performing the inference; an `invoke_agent` span performing no inference should not carry usage unless explicitly documented as aggregate. 2. **Tool spans with zero usage but nonzero latency.** `execute_tool` child spans showed `gen_ai.tool.name` and duration but no `gen_ai.usage.*`. Correct. The tell was that the parent's input token total exceeded the sum of `chat` children by exactly the token cost of the tool-result re-injection turns — meaning the parent was counting tokens the children never saw. 3. **`gen_ai.usage.output_tokens` on the parent that was not the sum of child outputs.** The delta matched the tokens of the final assistant message that terminated the loop, which was emitted on the parent rather than as a child `chat` span. 4. **Context-length drift.** `gen_ai.request.max_tokens` on the parent was set, but the sum of child `input_tokens` grew monotonically across steps with no corresponding `gen_ai.usage.input_tokens` on the step spans — the accumulation lived only on the parent, so per-step context growth was invisible. 5. **Retry duplication.** A retried `chat` child emitted usage twice (two spans, same `gen_ai.request.model`, overlapping timestamps, no `gen_ai.response.id`). The parent aggregated both, double-counting. The structural signal was two spans sharing a logical call but differing only in span ID. ## Condition of Validity The invariant holds — parent usage equals a genuine measurement — only when *all* of the following are true: - The parent span performs exactly one inference call and has no `chat` children, **or** - The parent carries no `gen_ai.usage.*` at all and consumers are documented to sum leaf `chat` spans, **or** - The parent carries usage explicitly tagged as aggregate (e.g., a non-standard `gen_ai.usage.aggregate = true` or a documented `invoke_agent` aggregation contract) and every contributing child is present and non-retried. The invariant is violated the moment a parent `invoke_agent` span emits `gen_ai.usage.*` while also having `chat` descendants and no aggregate marker. This is the boundary: it is valid to measure at leaves or to aggregate at the root, but the conventions do not define which, so a trace that does both without disambiguation is ambiguous and unsafe to consume. ## Decision Boundary Use the following decision rule when ingesting a trace: - If a span has `gen_ai.usage.input_tokens` **and** has descendant spans with `gen_ai.operation.name = "chat"` **and** no aggregate marker → treat the parent usage as *untrusted synthesized*; recompute from leaves. - If two leaf `chat` spans share `gen_ai.request.model` and overlap in time with no distinct `gen_ai.response.id` → treat one as a retry; do not sum both. - If `sum(child.input_tokens) != parent.input_tokens` and the delta is positive and stable across steps → the parent is counting re-injected tool context; do not use parent usage for context-window estimation. - If only `gen_ai.usage.total_tokens` is present with no split → do not attempt to derive input/output; the split is unrecoverable and any derived value violates the contract. The boundary is crossed (and the trace must be quarantined from cost accounting) when the parent/leaf reconciliation residual exceeds a threshold you cannot attribute to a known re-injection turn. ## Operational Effect Consumers that trusted parent usage over-counted cost by 18–40% in the observed traces (tool re-injection plus retry duplication), and context-window guards that read parent `input_tokens` under-counted per-step growth, allowing a step to exceed the model window before the guard fired. The correct operational posture is: **treat leaf `chat` span usage as the only measured quantity; treat parent `invoke_agent` usage as a claim requiring the aggregate marker and retry deduplication.** Emit an explicit aggregate attribute if you must aggregate, and never let a synthesized total share the attribute key of a measurement without a provenance signal. ```python from dataclasses import dataclass class TokenAccountingInvariantError(RuntimeError): """Raised when a GenAI agent span's usage attributes cannot be reconciled against its chat descendants under the OpenTelemetry GenAI conventions.""" @dataclass class Span: span_id: str operation: str # "invoke_agent" | "chat" | "execute_tool" input_tokens: int | None output_tokens: int | None response_id: str | None aggregate_marker: bool parent_id: str | None def reconcile_agent_usage(parent: Span, children: list[Span], residual_tolerance: int = 0) -> dict: if parent.operation != "invoke_agent": raise TokenAccountingInvariantError( f"expected invoke_agent parent, got {parent.operation!r}") chat_children = [c for c in children if c.operation == "chat"] # Deduplicate retries: same response_id -> keep one; missing response_id # with identical model+overlap cannot be safely deduped, so reject. seen: dict[str, Span] = {} for c in chat_children: if c.response_id is None: raise TokenAccountingInvariantError( f"chat span {c.span_id} lacks gen_ai.response.id; " "cannot deduplicate retries") seen.setdefault(c.response_id, c) unique = list(seen.values()) leaf_in = sum(c.input_tokens or 0 for c in unique) leaf_out = sum(c.output_tokens or 0 for c in unique) if parent.input_tokens is None and parent.output_tokens is None: return {"input_tokens": leaf_in, "output_tokens": leaf_out, "source": "leaf_sum"} if unique and not parent.aggregate_marker: raise TokenAccountingInvariantError( f"parent {parent.span_id} emits usage with {len(unique)} chat " "descendants but no aggregate marker; usage is synthesized, " "not measured") residual_in = (parent.input_tokens or 0) - leaf_in residual_out = (parent.output_tokens or 0) - leaf_out if abs(residual_in) > residual_tolerance or abs(residual_out) > residual_tolerance: raise TokenAccountingInvariantError( f"parent/leaf residual exceeds tolerance: " f"in={residual_in}, out={residual_out}") return {"input_tokens": parent.input_tokens, "output_tokens": parent.output_tokens, "source": "parent_aggregate"} ```