{
  "schema_version": "1.3.0",
  "slug": "why-does-an-instance-of-opentelemetry-genai-instrumentation-silently-drop-tool-call-child-spans-when-the-parent-llm-span-closes-before-the-tool-execut",
  "title": "Why does an instance of OpenTelemetry GenAI instrumentation silently drop tool-call child spans when the parent LLM span closes before the tool executor returns",
  "date_of_record": "2026 November 18",
  "scope": "Applies to OpenTelemetry GenAI semantic conventions (`gen_ai.*`) instrumentation where an LLM span is emitted with `gen_ai.operation.name` in {`chat`, `execute_tool`} and tool calls are modeled as child spans under the model invocation that requested them. Does not apply to flat trace models where tool spans are siblings of the model span, nor to async generators that keep the parent span context alive via explicit `Context` propagation.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/why-does-an-instance-of-opentelemetry-genai-instrumentation-silently-drop-tool-call-child-spans-when-the-parent-llm-span-closes-before-the-tool-execut.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/why-does-an-instance-of-opentelemetry-genai-instrumentation-silently-drop-tool-call-child-spans-when-the-parent-llm-span-closes-before-the-tool-execut.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/why-does-an-instance-of-opentelemetry-genai-instrumentation-silently-drop-tool-call-child-spans-when-the-parent-llm-span-closes-before-the-tool-execut.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1478,
    "python_slice_tokens": 390,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The GenAI semantic conventions treat a tool call as a *consequence* of a model response: the model emits `tool_calls`, and the runtime executes them. The instrumentation boundary is ambiguous about **who owns the span lifetime**. Two legitimate readings exist: 1. The tool span is a child of the LLM span because the model *requested* it — therefore its lifeti...",
    "what_was_observed": "A chat-completion span (`gen_ai.operation.name=chat`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`) was ended synchronously once the streaming response completed and usage was finalized. The tool executor was invoked in a `ThreadPoolExecutor` and returned ~40ms later. The resulting `execute_tool` spans carried a valid `parent_span_id` pointing at the ended chat span, but: - Backend trace assembly showed ...",
    "condition_of_validity": "This boundary holds only when **all** of the following are true: - The LLM span is ended (or its `Context` detached) before the tool executor returns. - Tool spans are parented via the ambient active context rather than an explicitly captured `Context` object. - The SDK's `NonRecordingSpan` propagation behavior treats an ended parent as non-recording (this i...",
    "decision_boundary": "Choose **explicit context capture** over ambient parenting when tool execution is asynchronous or delegated to a pool. Capture the LLM span's `Context` *before* ending it, and pass that `Context` into the executor so `start_as_current_span(context=captured_ctx)` parents correctly. Do **not** rely on `start_as_current_span` without a `context=` argument in a ...",
    "operational_effect": "The practical consequence is a trace that *appears* complete in code review and *appears* broken in production: model spans with `tool_calls` in their response attributes but no corresponding `execute_tool` children. Token accounting is unaffected, which masks the bug — `gen_ai.usage.*` metrics remain accurate because they live on the model span. Only the ca..."
  },
  "matched_failure_symptoms": [
    "SUBPROCESS_PIPE_HANG_OR_FD_LEAK"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "e58a3ddee138598a5e88b705ed0a4f0ea35351a0b2c37e58facbc375394b5312",
    "verified_classes": [
      "OrphanedToolSpanError",
      "SpanRecord"
    ],
    "verified_functions": [
      "assert_tool_span_exportable",
      "emit_tool_span"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 3,
    "raised_exceptions": [
      "OrphanedToolSpanError"
    ],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [
      "__future__",
      "dataclasses"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
