Align OTel LLM-parent to the per-instance fan-out dispatch span#195
Merged
Conversation
Align OTel's _resolve_llm_parent with the spec ruling (review-nested-fan-out-lineage): an orphaned LLM span (calling node has no open span) inside a fan-out instance now parents under the per-instance fan-out dispatch span, matching the Langfuse observer, instead of falling through to the subgraph or invocation span. Top-level instance parity only. The generalized nearest-open-ancestor walk -- nested instances at any depth (where the parity key can mis-resolve to a sibling top-level instance) and the instance-vs-deeper-subgraph ordering -- rides the pending spec observability fallback clause and fixture.
There was a problem hiding this comment.
Pull request overview
Aligns the OpenTelemetry observer’s LLM span parenting behavior with the Langfuse observer when an LLM provider span is emitted from “orphaned” call sites inside a top-level fan-out instance (i.e., no calling-node span is open). This improves observability parity by ensuring the LLM span parents under the per-instance fan-out dispatch span.
Changes:
- Add a fan-out-instance dispatch-span fallback in
OTelObserver._resolve_llm_parentbefore the subgraph/invocation fallbacks. - Add a regression test asserting the orphaned LLM span parents under the per-instance dispatch span in a top-level fan-out instance.
- Document the fix in
CHANGELOG.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
src/openarmature/observability/otel/observer.py |
Adds per-instance fan-out dispatch fallback for orphaned LLM span parent resolution. |
tests/unit/test_observability_otel.py |
Adds regression coverage for fan-out-instance parenting of orphaned LLM spans. |
CHANGELOG.md |
Notes the OTel parenting change and its current scope limitations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
PR review follow-ups: - _resolve_llm_parent docstring now lists the per-instance fan-out dispatch fallback added in this PR. - Drop the manual dispatch_span.end() in the new test: shutdown() drains fan_out_instance_spans and ends the span, so the manual end double-ended it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
An LLM provider span whose calling node has no open span (for example a provider
call originating from middleware or a wrapper) and which fires inside a fan-out
instance now parents under the per-instance fan-out dispatch span in the OTel
observer, matching the Langfuse observer, instead of falling through to the
subgraph or invocation span. This resolves a divergence between the two
observers.
_resolve_llm_parentgains a fallback between the exact calling-node match andthe subgraph walk, mirroring the Langfuse
_resolve_llm_parent_observation_idfallback. Observability §5.5 defines no parent for an orphaned LLM span; the
per-instance instance span is the canonical choice (the §6 driving-span stack,
proposal 0045 §3.4, and §4.4's detached shape all point to it).
Scope
Top-level instance parity only. The generalized nearest-open-ancestor fallback
(nested fan-out instances at any depth, where the parity key can mis-resolve to a
sibling top-level instance, plus the instance-vs-deeper-subgraph ordering) is
pending an observability spec clause and fixture, and will land in both observers
together against that fixture.
Tests
New regression test (
test_llm_span_parents_under_fan_out_instance_dispatch)asserting an orphaned LLM span in a top-level fan-out instance parents under the
per-instance dispatch span; it fails without the fallback (the span would
otherwise be a trace root). Full suite green (1475), ruff and pyright clean.