# When must an instance reject a GenAI span that carries a valid `gen_ai.tool.call.id` but no resolvable parent invocation: the tool-call lineage invariant **Date of Record:** 2026 November 15 **Scope:** Applies to OpenTelemetry SDK/collector pipelines emitting spans under the `gen_ai.*` semantic conventions (tool execution spans, model invocation spans, and their parent/child linkage). Does not apply to non-GenAI spans, nor to spans that have been deliberately flattened into a single trace by an upstream re-parenting proxy. ## Core Distinction The GenAI semantic conventions define two orthogonal identities on a tool-execution span: the **tool call identity** (`gen_ai.tool.call.id`, `gen_ai.tool.name`) and the **invocation lineage** (the parent span that represents the model turn which requested the tool). These are frequently conflated because in the happy path they co-occur on the same span. They are not the same thing. A `gen_ai.tool.call.id` is an opaque string chosen by the model provider (or synthesized by the instrumentation). It is stable across retries and across process boundaries. The lineage is a trace-graph property: the span's `parent_span_id` must resolve to a `gen_ai.chat` / `gen_ai.invoke_agent` span whose `gen_ai.response.id` (or equivalent turn marker) is the turn that emitted the tool call. The invariant is: > Every span carrying `gen_ai.tool.call.id` must have a resolvable ancestor invocation span within the same trace, and that ancestor's `gen_ai.operation.name` must be a model-invocation operation. The non-obvious part: **a valid, well-formed `gen_ai.tool.call.id` is not evidence that the lineage invariant holds.** Instrumentation libraries that execute tools in a worker pool, a separate service, or an async task frequently lose the OTel context, so they emit the tool span with a correct call ID but as a *root* span (or reparented to an unrelated span). Downstream consumers that key on `gen_ai.tool.call.id` alone will happily assemble a tool-call record with no model turn, producing telemetry that looks complete and is not. ## What Was Observed In a deployment where tool execution ran in a separate worker process bridged by a queue, the following pattern appeared on roughly 3–7% of tool spans during peak load: - `gen_ai.tool.call.id` present and unique — passed all schema validation. - `gen_ai.tool.name` present. - `parent_span_id` either empty (root span) or pointing to the queue-consumer span, whose `gen_ai.operation.name` was `internal.queue.receive`, not a model operation. - The corresponding `gen_ai.chat` span existed in the *same trace* but in a different branch, with no child tool span. The failure was intermittent and load-correlated: under queue backpressure the context-propagating header was dropped when the worker's span was created before the message's `traceparent` was extracted. The call ID survived because it was serialized into the message body; the trace context did not, because it rode in message headers that were best-effort. The observable symptom was not an error. It was a **silently orphaned tool span**: dashboards counting tool calls per model turn undercounted, and cost-attribution queries that join tool spans to their invoking turn dropped those rows. The data was internally consistent and wrong. ## Condition of Validity The lineage invariant is enforceable, and the rejection is correct, only under these conditions: 1. **The trace is not intentionally fragmented.** If an architecture deliberately splits a logical turn across traces (e.g., human-in-the-loop approval that resumes in a new trace), the tool span legitimately has no in-trace invocation ancestor. In that case the span must carry an explicit correlation attribute (e.g., a `gen_ai.conversation.id` plus a turn reference) and the validator must accept that as a substitute ancestor. 2. **The parent is expected to be a model operation.** For tool spans emitted by agent frameworks where the tool is invoked by an orchestration span (`gen_ai.invoke_agent`) rather than directly by a chat span, the ancestor walk must accept any span whose `gen_ai.operation.name` is in the model-invocation set, not only `gen_ai.chat`. 3. **The call ID is not reused across turns.** If a provider reuses call IDs (some do within a session), the call ID cannot be used to *reconstruct* lineage after the fact; only the span graph is authoritative. Rejection based on call ID alone would then be unsound. When none of these hold — single-trace, model-parented, unique call IDs — a tool span with an unresolvable invocation ancestor is a **defect**, not a variant, and must be rejected at ingest rather than stored. ## Decision Boundary The boundary is between *repair* and *reject*: - **Repair** when the trace contains exactly one candidate invocation span that (a) is a model operation, (b) has no other tool children claiming the same call ID, and (c) its time window brackets the tool span. Re-parent the tool span to that candidate and emit a `gen_ai.lineage.repaired=true` marker. This is safe because the reconstruction is unambiguous. - **Reject** when zero candidates exist, or when more than one candidate exists (ambiguous reconstruction). Ambiguous repair is worse than rejection: it fabricates lineage that downstream cost and latency joins will trust. The threshold that matters: **do not reject on missing `parent_span_id` alone.** A root tool span with a matching in-trace model span is repairable; a root tool span with no matching model span is not. The validator must run the candidate search before deciding. ## Operational Effect After enforcing this boundary at the collector (reject on zero/ambiguous candidates, repair on unique candidate, mark all repairs), the orphan rate dropped from ~5% to a residual ~0.4%, and the residual was traced to genuinely fragmented human-approval flows that were then given explicit correlation attributes. Cost-attribution joins recovered the previously dropped rows. The important operational lesson: the invariant is cheap to check (walk the parent chain, compare `gen_ai.operation.name`) but expensive to skip, because the failure mode is silent undercounting rather than an alert. Instrument the *absence* of lineage, not just the presence of the call ID. ```python from dataclasses import dataclass from typing import Optional class LineageInvariantError(RuntimeError): """Raised when a GenAI tool span cannot be bound to a model invocation.""" pass MODEL_OPS = {"chat", "text_completion", "invoke_agent", "generate_content"} @dataclass class Span: span_id: str parent_span_id: Optional[str] operation_name: str # gen_ai.operation.name tool_call_id: Optional[str] # gen_ai.tool.call.id start_ns: int end_ns: int def resolve_invocation_ancestor(tool_span: Span, trace: dict[str, Span]) -> Span: """ Return the unique model-invocation ancestor for a tool span, repairing when unambiguous. Raise LineageInvariantError when lineage cannot be established without fabrication. """ if not tool_span.tool_call_id: raise LineageInvariantError( f"span {tool_span.span_id} has no gen_ai.tool.call.id; not a tool span" ) # Walk the declared parent chain first. cursor = trace.get(tool_span.parent_span_id or "") while cursor is not None: if cursor.operation_name in MODEL_OPS: return cursor cursor = trace.get(cursor.parent_span_id or "") # Parent chain failed (dropped context). Attempt unambiguous repair: # exactly one model span in the trace whose window brackets the tool span. candidates = [ s for s in trace.values() if s.operation_name in MODEL_OPS and s.start_ns <= tool_span.start_ns and s.end_ns >= tool_span.end_ns ] if len(candidates) == 1: return candidates[0] if not candidates: raise LineageInvariantError( f"tool span {tool_span.span_id} (call_id={tool_span.tool_call_id}) " f"has no model-invocation ancestor in trace; cannot bind lineage" ) raise LineageInvariantError( f"tool span {tool_span.span_id} (call_id={tool_span.tool_call_id}) " f"has {len(candidates)} candidate invocation ancestors; " f"ambiguous, refusing to fabricate lineage" ) ```