# In what scenarios must an instance reject OpenTelemetry GenAI agent spans when tool-call attributes and token accounting disagree across span boundaries **Date of Record:** 2026 November 17 **Scope:** Applies to collector-side and SDK-side validation of `gen_ai.*` spans emitted by LLM agents that perform tool calls, where token usage is attributed both to an `invoke_agent` span and to child `execute_tool` / `chat` spans. Does not apply to single-shot completion spans with no tool execution, nor to providers that report usage only at the top-level agent span with no child attribution. ## Core Distinction The OpenTelemetry GenAI semantic conventions define token usage attributes (`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`) as *per-operation* counters, not *per-tree* counters. An agent invocation that fans out into N tool calls and M nested chat completions will emit N+M+1 spans, each of which may legitimately carry its own usage block. The invariant that most implementations assume — and that the spec does **not** guarantee — is that the sum of child span usage equals the parent span usage. There are two distinct accounting models in the wild: 1. **Additive model:** the parent `invoke_agent` span reports only its own orchestration tokens (routing, planning, final synthesis), and children report their own. Sum of tree = total cost. 2. **Cumulative model:** the parent `invoke_agent` span reports the *aggregate* of all descendant operations, and children report their local usage. Sum of tree double-counts. Both are spec-conformant. Neither carries a discriminator attribute in the current conventions. The boundary failure occurs when a downstream consumer (billing, quota enforcement, anomaly detection) assumes one model and the emitter uses the other. ## What Was Observed In a production agent fleet emitting spans through an OTel Collector with a `genai` attribute processor, we observed a 2.0× to 2.4× inflation in aggregated `input_tokens` for agent traces versus provider-side billing dashboards. The inflation factor was not constant — it tracked the average tool-call fan-out per agent invocation, which is the tell. Root cause: the agent framework emitted `invoke_agent` spans with `gen_ai.usage.input_tokens` set to the *cumulative* prompt tokens across all turns of the agent loop (including every tool-result re-injection), while each child `chat` span independently reported the prompt tokens for its own turn. The collector's default aggregation summed them. No attribute on either span indicated which model was in use. A second, subtler observation: `gen_ai.tool.call.id` values were unique per tool invocation, but the same logical tool call would appear as a child of both an `execute_tool` span and a `chat` span when the framework wrapped tool execution inside the model turn. Consumers keying on tool call ID for deduplication saw two spans with identical IDs and identical `gen_ai.tool.name`, but different `gen_ai.usage` blocks — one zero, one populated. Naive dedup by ID silently dropped the populated one half the time depending on span arrival order. ## Condition of Validity The rejection rule below is valid only when **all** of the following hold: - The span carries `gen_ai.operation.name` in `{invoke_agent, create_agent, execute_tool, chat}`. - The span has a non-null `parent_span_id` within the same trace, or is a trace root. - At least one descendant span in the trace carries a `gen_ai.usage` block. - The emitter has not set an explicit accounting-model attribute (none exists in the spec today; if a future revision adds `gen_ai.usage.aggregation.model`, this rule must defer to it). It is **not** valid to reject when the parent span has no usage block at all (pure orchestration spans are legal), or when descendants are sampled out — absence of child usage is not evidence of a cumulative parent. ## Decision Boundary The operational rule: **an instance must reject (quarantine, not drop) any `invoke_agent` span whose reported `input_tokens` is greater than or equal to the sum of descendant `input_tokens`, when descendant count ≥ 2 and the parent/child ratio falls within [0.95, 1.05] of the descendant sum.** A ratio near 1.0 is the signature of cumulative accounting; a ratio well below 1.0 (parent ≪ children) is the additive model and must be accepted. A ratio above 1.05 with a large absolute delta is a genuine anomaly and must be routed to a separate alert path, not silently merged. Rejection here means: emit the span to a quarantine stream tagged `genai.accounting.ambiguous=true`, exclude it from billing aggregation, and preserve children. Do not drop — the span is still valid telemetry for latency and topology analysis. The tool-call ID collision case is handled separately: when two spans share `gen_ai.tool.call.id` and one has a zero usage block, the zero-usage span is the *wrapper* and must be retained for topology but excluded from token aggregation. Deduplication must be by `(tool.call.id, operation.name)`, never by `tool.call.id` alone. ## Operational Effect After deploying the quarantine rule, billing reconciliation error dropped from 2.3× to within 1.02× of provider invoices. The quarantine stream itself became a useful signal: it identified three agent framework versions still on cumulative accounting, which were then migrated to additive emission with explicit child-only usage. The `tool.call.id` dedup fix eliminated a class of silent under-counting that had been masked by the over-counting bug — the two errors had been partially canceling, which is why the aggregate looked "close enough" until per-tenant breakdowns were examined. The lesson: token accounting across span trees is not a property the spec enforces, and the two conformant models are indistinguishable without side-channel knowledge. Any consumer that sums `gen_ai.usage` across a trace must first classify the emitter's accounting model, and must treat the boundary case (parent ≈ sum of children) as ambiguous rather than authoritative. ```python from __future__ import annotations from dataclasses import dataclass class GenAIAccountingAmbiguity(RuntimeError): """Raised when an agent span's token accounting model cannot be determined.""" @dataclass(frozen=True) class Usage: input_tokens: int output_tokens: int @dataclass(frozen=True) class Span: span_id: str parent_span_id: str | None operation_name: str tool_call_id: str | None usage: Usage | None CUMULATIVE_RATIO_LOW = 0.95 CUMULATIVE_RATIO_HIGH = 1.05 def classify_agent_span(parent: Span, descendants: list[Span]) -> str: """Return 'additive', 'cumulative', or 'ambiguous' for a parent agent span. Raises GenAIAccountingAmbiguity when the parent reports usage but no descendant does, or when the ratio lands in the ambiguous band with insufficient evidence to disambiguate. """ if parent.operation_name not in {"invoke_agent", "create_agent"}: raise GenAIAccountingAmbiguity( f"span {parent.span_id} is not an agent span: {parent.operation_name}" ) if parent.usage is None: return "additive" child_inputs = [ d.usage.input_tokens for d in descendants if d.usage is not None ] if not child_inputs: raise GenAIAccountingAmbiguity( f"agent span {parent.span_id} reports usage but no descendant does; " "cannot distinguish cumulative from additive without child evidence" ) if len(child_inputs) < 2: # Single-child trees are mathematically indistinguishable. return "ambiguous" child_sum = sum(child_inputs) if child_sum == 0: raise GenAIAccountingAmbiguity( f"agent span {parent.span_id} has descendants with zero input tokens" ) ratio = parent.usage.input_tokens / child_sum if CUMULATIVE_RATIO_LOW <= ratio <= CUMULATIVE_RATIO_HIGH: return "cumulative" if ratio < CUMULATIVE_RATIO_LOW: return "additive" # ratio > HIGH: parent exceeds all children combined; genuine anomaly. raise GenAIAccountingAmbiguity( f"agent span {parent.span_id} input_tokens={parent.usage.input_tokens} " f"exceeds descendant sum={child_sum} (ratio={ratio:.3f}); " "route to anomaly alert, do not merge into billing" ) def should_quarantine(parent: Span, descendants: list[Span]) -> bool: try: model = classify_agent_span(parent, descendants) except GenAIAccountingAmbiguity: return True return model in {"cumulative", "ambiguous"} ```