Add detached-trace invocation span (0061)#168
Merged
Conversation
The OTel observer now synthesizes an openarmature.invocation span at the root of each detached trace (a detached subgraph and each detached fan-out instance), carrying the parent's shared invocation_id and the detached unit's own entry_node, with the detached subgraph/instance span nested beneath it. A raising detached subgraph surfaces ERROR plus the error category and an exception event on both the parent dispatch span and the detached invocation span. Observer-side only: no graph-engine change, and the Langfuse observer is unchanged. Pins the spec submodule to v0.61.0 and brings conformance fixtures 008 (rewritten) and 058 (newly covered) live.
There was a problem hiding this comment.
Pull request overview
Updates the OpenTelemetry observer to align with spec proposal 0061 by introducing a synthetic openarmature.invocation span as the root container for each detached trace (detached subgraphs and detached fan-out instances), and propagating error status/exception information across the parent dispatch span and the detached invocation span.
Changes:
- Add detached-trace invocation span creation and detached error propagation behavior in the OTel observer.
- Update unit + conformance tests to assert the new detached invocation/root invariants and wire fixture
058. - Bump pinned spec version references to
0.61.0across package metadata, smoke tests, docs, and conformance manifest.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
src/openarmature/observability/otel/observer.py |
Synthesizes detached-trace invocation spans, propagates detached errors, and adjusts close/drain logic for new span layer. |
tests/unit/test_observability_otel.py |
Updates unit assertions for detached traces to include detached invocation span + shared invocation_id. |
tests/conformance/test_observability.py |
Refactors detached fixture runner, updates fixture 008 assertions, and adds wiring/assertions for fixture 058. |
tests/test_smoke.py |
Updates expected __spec_version__ to 0.61.0. |
src/openarmature/__init__.py |
Bumps __spec_version__ to 0.61.0. |
pyproject.toml |
Bumps [tool.openarmature].spec_version to 0.61.0. |
docs/concepts/observability.md |
Documents detached trace behavior rooted in a detached invocation span with shared invocation_id. |
conformance.toml |
Marks proposal 0061 implemented and wires related conformance fixtures. |
src/openarmature/AGENTS.md |
Regenerates bundled agent guide references to spec v0.61.0. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
errored_detached_keys gates the synthetic close paths' default set_status(OK) so a detached-trace ERROR survives export. The set is invocation-scoped but never cleared mid-invocation, so a detached prefix that errors and then re-runs successfully within the same invocation (cyclic or fire-and-forget re-entry) could leave the later success span UNSET instead of OK. Discard the key when a fresh detached invocation span opens at it (the only point keys are introduced), so each generation's close reflects only its own status. Reading the live span status was rejected as it depends on _Span.status, which is not part of the public OTel Span interface.
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.
What
The OTel observer now synthesizes an
openarmature.invocationspan at the root of each detached trace (a detached subgraph, and each detached fan-out instance). The synthesized span carries the parent invocation's sharedinvocation_idand the detached unit's ownentry_node, with the detached subgraph/instance span nested beneath it.A raising detached subgraph surfaces ERROR status, the error category, and an exception event on both the parent dispatch span and the detached invocation span. The OTel SDK's "OK overrides ERROR" behaviour is handled explicitly so a synthetic close cannot downgrade an already-errored span.
Scope
Observer-side only: no graph-engine change, and the Langfuse observer is unchanged.
Spec and conformance
Pins the spec submodule to v0.61.0 and marks proposal 0061 implemented (since 0.15.0) in
conformance.toml. Brings two conformance fixtures live: 008 (rewritten with the invocation-root invariants) and 058 (newly covered). Docs and the bundled AGENTS.md are regenerated to match.__version__stays at 0.14.0; this is the first PR of the v0.15.0 cycle, and the version bump lands at release.