narrativetrace-otel 0.1.0__tar.gz

narrativetrace_otel-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.mutmut-cache
+mutants/
+# pytest-benchmark autosave (poe bench-gate): per-machine comparison history, never comparable
+# across machines -- stays local to whichever machine runs the nightly, like .venv/.uv-cache.
+.benchmarks/
+htmlcov/
+.coverage
+.coverage.*
+dist/
+build/
+*.egg-info/
+
+# Cache for security-tool binaries auto-fetched by scripts/run_security_tool.py
+.tools/
+
+# Local tooling state (contains credentials — never commit)
+.devcontainer/claude-home/
+.agent-run*
+
+# Local tooling state (holds host-absolute paths)
+.claude/settings.local.json

narrativetrace_otel-0.1.0/LICENSE

@@ -0,0 +1,99 @@
+Business Source License 1.1
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             Empower Agile
+
+Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version {{VERSION}}. The Licensed Work is (c) 2026 Empower Agile.
+
+Additional Use Grant: You may make production use of the Licensed Work for any
+                      purpose, including internal use and use in products and
+                      services you provide to your own customers, provided that
+                      such production use does not include offering the
+                      Licensed Work, or a product or service whose value
+                      derives substantially from the Licensed Work, to third
+                      parties as a logging, tracing, or code-narrative product
+                      or service.
+
+Change Date:          Four years from the date the Licensed Work is published. ({{CHANGE_DATE}} for this version)
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Empower Agile at hello@narrativetrace.ai.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

narrativetrace_otel-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.5
+Name: narrativetrace-otel
+Version: 0.1.0
+Summary: OpenTelemetry span bridge for narrativetrace traces
+Project-URL: Homepage, https://github.com/narrativetrace/narrativetrace-python
+Project-URL: Source, https://github.com/narrativetrace/narrativetrace-python
+Author: narrativetrace contributors
+License-Expression: BUSL-1.1
+License-File: LICENSE
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: narrativetrace
+Requires-Dist: opentelemetry-api>=1.20
+Description-Content-Type: text/markdown
+
+# narrativetrace-otel
+
+OpenTelemetry span bridge for [narrativetrace](../narrativetrace) traces.
+
+Two entry points:
+
+* `OtelTraceEventListener` — a live event consumer that opens a span on each enter and
+  closes it on the matching exit, anchored to the **event timestamps** (not processing
+  time). Orphaned spans are evicted by a bounded `PerishableMap`.
+* `TraceSpanExporter` — a batch exporter that walks a completed `TraceTree`/`TraceNode`
+  forest and emits a nested span per node.

narrativetrace_otel-0.1.0/README.md

@@ -0,0 +1,11 @@
+# narrativetrace-otel
+
+OpenTelemetry span bridge for [narrativetrace](../narrativetrace) traces.
+
+Two entry points:
+
+* `OtelTraceEventListener` — a live event consumer that opens a span on each enter and
+  closes it on the matching exit, anchored to the **event timestamps** (not processing
+  time). Orphaned spans are evicted by a bounded `PerishableMap`.
+* `TraceSpanExporter` — a batch exporter that walks a completed `TraceTree`/`TraceNode`
+  forest and emits a nested span per node.

narrativetrace_otel-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "narrativetrace-otel"
+version = "0.1.0"
+description = "OpenTelemetry span bridge for narrativetrace traces"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "BUSL-1.1"
+# See packages/narrativetrace/pyproject.toml: one byte-identical copy of the root LICENSE per
+# distribution, because PEP 639 forbids reaching out of the project directory.
+license-files = ["LICENSE"]
+authors = [{ name = "narrativetrace contributors" }]
+classifiers = ["Typing :: Typed"]
+dependencies = [
+    "narrativetrace",
+    "opentelemetry-api>=1.20",
+]
+
+[project.urls]
+Homepage = "https://github.com/narrativetrace/narrativetrace-python"
+Source = "https://github.com/narrativetrace/narrativetrace-python"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/narrativetrace_otel"]
+
+[dependency-groups]
+dev = [
+    "opentelemetry-sdk>=1.20",
+]

narrativetrace_otel-0.1.0/src/narrativetrace_otel/__init__.py

@@ -0,0 +1,17 @@
+"""OpenTelemetry span bridge for narrativetrace traces.
+
+Two entry points share the :mod:`narrativetrace_otel.attributes` mapper:
+
+* :class:`~narrativetrace_otel.listener.OtelTraceEventListener` — live, span-per-event.
+* :class:`~narrativetrace_otel.exporter.TraceSpanExporter` — batch, tree-to-spans.
+"""
+
+from narrativetrace_otel.exporter import TraceSpanExporter
+from narrativetrace_otel.listener import OtelTraceEventListener
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OtelTraceEventListener",
+    "TraceSpanExporter",
+]

narrativetrace_otel-0.1.0/src/narrativetrace_otel/attributes.py

@@ -0,0 +1,250 @@
+"""Maps NarrativeTrace signatures, span contexts, and outcomes to OTel span attributes.
+
+``SpanContextAttributeMapper`` — the single source of truth shared by the live
+:class:`~narrativetrace_otel.listener.OtelTraceEventListener` and the batch
+:class:`~narrativetrace_otel.exporter.TraceSpanExporter`.
+
+Trace-level attributes (``narrative.service.*``, ``narrative.http.*``, user identity) apply only
+to root spans; span-level attributes (class, method, params) apply to every span. Structured
+:class:`~narrativetrace.values.RenderedValue` values flatten to natively-typed OTel attributes
+(int, float, bool, homogeneous arrays); object fields dot-flatten to depth 3. When a structured
+value is absent, a string-inference fallback parses the flat rendered string.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from opentelemetry.trace import Span, Status, StatusCode
+
+from narrativetrace.canonical import SCHEMA_VERSION
+from narrativetrace.context_export import export as context_export
+from narrativetrace.outcomes import Incomplete, Returned, Threw, TraceOutcome
+from narrativetrace.values import (
+    BoolVal,
+    FloatVal,
+    InstantVal,
+    IntVal,
+    ListVal,
+    ObjectVal,
+    RenderedValue,
+    StringVal,
+)
+
+if TYPE_CHECKING:
+    from narrativetrace.concurrency import ConcurrencyInfo
+    from narrativetrace.nodes import TraceNode
+    from narrativetrace.signature import MethodSignature, ParameterCapture
+    from narrativetrace.span import SpanContext
+
+MAX_FLATTEN_DEPTH = 3
+
+# OTel attribute values are str | bool | int | float | sequences thereof.
+AttributeValue = str | bool | int | float | list[str] | list[bool] | list[int] | list[float]
+Sink = Callable[[str, AttributeValue], None]
+
+# Root-only trace-level fields: attribute key -> SpanContext extractor.
+_TRACE_LEVEL_FIELDS: list[tuple[str, Callable[[SpanContext], object]]] = [
+    ("narrative.service.name", lambda sc: sc.service_name),
+    ("narrative.service.version", lambda sc: sc.service_version),
+    ("narrative.service.environment", lambda sc: sc.environment),
+    ("narrative.http.method", lambda sc: sc.http_method),
+    ("narrative.http.route", lambda sc: sc.http_route),
+    ("narrative.client_ip", lambda sc: sc.client_ip),
+    ("narrative.enduser.id", lambda sc: sc.enduser_id),
+    ("narrative.session.id", lambda sc: sc.session_id),
+    ("narrative.tenant.id", lambda sc: sc.tenant_id),
+]
+
+
+def set_span_attributes(sig: MethodSignature, span: Span) -> None:
+    """Sets span-level attributes (class, method, params) from ``sig``."""
+    span.set_attribute("narrative.class", sig.class_name)
+    span.set_attribute("narrative.method", sig.method_name)
+    for param in sig.parameters:
+        _set_param(span.set_attribute, f"narrative.param.{param.name}", param)
+
+
+def set_concurrency_attributes(info: ConcurrencyInfo | None, span: Span) -> None:
+    """Sets concurrency attributes from ``info`` when present."""
+    if info is None:
+        return
+    span.set_attribute("narrative.concurrency.groupId", info.group_id)
+    span.set_attribute("narrative.concurrency.kind", info.kind.name)
+    span.set_attribute("narrative.concurrency.threadId", info.thread_id)
+    if info.thread_name is not None:
+        span.set_attribute("narrative.concurrency.threadName", info.thread_name)
+    span.set_attribute("narrative.concurrency.virtual", info.virtual)
+    if info.task_label is not None:
+        span.set_attribute("narrative.concurrency.taskLabel", info.task_label)
+
+
+def set_outcome_attributes(outcome: TraceOutcome | None, span: Span) -> None:
+    """Sets outcome attributes/status from ``outcome``."""
+    if isinstance(outcome, Returned):
+        if outcome.rendered_value is not None:
+            span.set_attribute("narrative.outcome", outcome.rendered_value)
+    elif isinstance(outcome, Threw):
+        span.set_status(Status(StatusCode.ERROR, str(outcome.exception)))
+        span.record_exception(outcome.exception)
+    elif isinstance(outcome, Incomplete):
+        span.set_attribute("narrative.outcome", "in-flight")
+
+
+def set_trace_identity_attributes(sc: SpanContext | None, span: Span) -> None:
+    """Sets ``narrative.trace_id`` / ``narrative.trace_name`` on every span for correlation."""
+    if sc is None:
+        return
+    span.set_attribute("narrative.trace_id", str(sc.trace_id))
+    span.set_attribute("narrative.trace_name", sc.trace_id.human_name())
+
+
+def set_nt_schema_attributes(sc: SpanContext | None, span: Span) -> None:
+    """Sets canonical ``nt.*`` schema attributes on the span."""
+    if sc is None:
+        return
+    span.set_attribute("nt.entryType", "entry")
+    span.set_attribute("nt.schemaVersion", SCHEMA_VERSION)
+    if sc.story_id is not None:
+        span.set_attribute("nt.storyId", sc.story_id)
+    if sc.chapter_id is not None:
+        span.set_attribute("nt.chapterId", sc.chapter_id)
+
+
+def set_trace_level_attributes(sc: SpanContext | None, span: Span) -> None:
+    """Sets root-only trace-level attributes (service/http/user identity) from ``sc``.
+
+    Adversarial-audit mirror (2026-09-02): a value set programmatically through
+    ``set_request_context``/``set_user_context`` (a custom integration, a test, a framework this
+    runtime ships no filter for) never passes through the HTTP middleware's own normalisation, so
+    this is the last point before it becomes a telemetry attribute -- control-stripped and
+    length-capped here regardless of how it arrived.
+    """
+    if sc is None:
+        return
+    for key, extractor in _TRACE_LEVEL_FIELDS:
+        value = extractor(sc)
+        if value is not None:
+            span.set_attribute(key, context_export(str(value)))
+
+
+def build_event_attributes(
+    sig: MethodSignature, outcome: TraceOutcome | None
+) -> dict[str, AttributeValue]:
+    """Builds parent-span event attributes from a child's signature and outcome."""
+    attrs: dict[str, AttributeValue] = {}
+    for param in sig.parameters:
+        if param.redacted or param.rendered_value == "":
+            continue
+        _set_param(_dict_sink(attrs), f"narrative.param.{param.name}", param, allow_lists=False)
+    _add_outcome_to_event(attrs, outcome)
+    return attrs
+
+
+def emit_child_event(parent_span: Span, child: TraceNode) -> None:
+    """Emits a child method completion as a timestamped event on the parent span."""
+    attrs = build_event_attributes(child.signature, child.outcome)
+    name = f"{child.signature.class_name}.{child.signature.method_name}"
+    timestamp = child.start_time_nanos + child.duration_nanos
+    parent_span.add_event(name, attributes=attrs, timestamp=timestamp)
+
+
+def _dict_sink(attrs: dict[str, AttributeValue]) -> Sink:
+    def sink(key: str, value: AttributeValue) -> None:
+        attrs[key] = value
+
+    return sink
+
+
+def _set_param(
+    sink: Sink, prefix: str, param: ParameterCapture, *, allow_lists: bool = True
+) -> None:
+    if param.redacted or param.rendered_value == "":
+        return
+    structured = param.structured_value
+    if structured is None:
+        sink(prefix, _typed_from_string(param.rendered_value))
+    else:
+        _flatten(structured, prefix, 0, sink, allow_lists=allow_lists)
+
+
+def _flatten(
+    value: RenderedValue, prefix: str, depth: int, sink: Sink, *, allow_lists: bool
+) -> None:
+    scalar = _scalar_native(value)
+    if scalar is not None:
+        sink(prefix, scalar)
+        return
+    if isinstance(value, ObjectVal) and depth < MAX_FLATTEN_DEPTH:
+        for key, field_value in value.fields.items():
+            _flatten(field_value, f"{prefix}.{key}", depth + 1, sink, allow_lists=allow_lists)
+    elif allow_lists and isinstance(value, ListVal):
+        array = _list_native(value)
+        if array is not None:
+            sink(prefix, array)
+    # NullVal, depth-exceeded ObjectVal, and (in events) ListVal are skipped.
+
+
+def _scalar_native(value: RenderedValue) -> AttributeValue | None:
+    if isinstance(value, StringVal):
+        return value.value
+    if isinstance(value, BoolVal):
+        return value.value
+    if isinstance(value, IntVal):
+        return value.value
+    if isinstance(value, FloatVal):
+        return value.value
+    if isinstance(value, InstantVal):
+        return value.epoch_millis
+    return None
+
+
+# Java emits homogeneous arrays only for these scalar types; all carry a ``.value`` field.
+_ARRAY_ELEMENT_TYPES = (StringVal, BoolVal, IntVal, FloatVal)
+
+
+def _list_native(value: ListVal) -> AttributeValue | None:
+    if not value.elements:
+        return None
+    first = type(value.elements[0])
+    if first not in _ARRAY_ELEMENT_TYPES:
+        return None
+    if any(type(element) is not first for element in value.elements):
+        return None
+    return [element.value for element in value.elements]  # type: ignore[attr-defined]
+
+
+def _typed_from_string(rendered: str) -> AttributeValue:
+    if rendered in ("true", "false"):
+        return rendered == "true"
+    parsed_int = _try_int(rendered)
+    if parsed_int is not None:
+        return parsed_int
+    parsed_float = _try_float(rendered)
+    if parsed_float is not None:
+        return parsed_float
+    if len(rendered) >= 2 and rendered.startswith('"') and rendered.endswith('"'):
+        return rendered[1:-1]
+    return rendered
+
+
+def _try_int(text: str) -> int | None:
+    try:
+        return int(text)
+    except ValueError:
+        return None
+
+
+def _try_float(text: str) -> float | None:
+    try:
+        return float(text)
+    except ValueError:
+        return None
+
+
+def _add_outcome_to_event(attrs: dict[str, AttributeValue], outcome: TraceOutcome | None) -> None:
+    if isinstance(outcome, Returned) and outcome.rendered_value is not None:
+        attrs["narrative.outcome"] = outcome.rendered_value
+    elif isinstance(outcome, Threw):
+        attrs["narrative.outcome"] = f"error: {outcome.exception}"

narrativetrace_otel-0.1.0/src/narrativetrace_otel/exporter.py

@@ -0,0 +1,68 @@
+"""Batch exporter for completed NarrativeTrace trees.
+
+``TraceSpanExporter``. Use this after capture when a full
+:class:`~narrativetrace.nodes.TraceNode` forest is in hand and should be published to an OTel
+backend. Parent-child structure is recreated by nesting span scopes during export; the exporter
+does not reuse the original span-context ids as OTel span ids. Nodes with
+:class:`~narrativetrace.outcomes.Incomplete` outcome export with ``narrative.outcome="in-flight"``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from opentelemetry.trace import Span, Tracer, use_span
+
+from narrativetrace.tree_walk import CYCLE_MARKER, DEPTH_LIMIT_MARKER, TreeWalk
+from narrativetrace_otel import attributes
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from narrativetrace.nodes import TraceNode
+
+_NANOS_PER_MILLI = 1_000_000.0
+
+_TRUNCATED_REASON = {DEPTH_LIMIT_MARKER: "depth-limit", CYCLE_MARKER: "cycle"}
+
+
+class TraceSpanExporter:
+    """Exports completed :class:`~narrativetrace.nodes.TraceNode` trees as nested OTel spans."""
+
+    def __init__(self, tracer: Tracer) -> None:
+        self._tracer = tracer
+
+    def export(self, roots: Iterable[TraceNode]) -> None:
+        """Exports each root node (and its subtree) as a span tree."""
+        walk = TreeWalk()
+        for root in roots:
+            self._export_node(root, is_root=True, walk=walk)
+
+    def _export_node(self, node: TraceNode, *, is_root: bool, walk: TreeWalk) -> None:
+        sig = node.signature
+        span = self._tracer.start_span(f"{sig.class_name}.{sig.method_name}")
+        attributes.set_span_attributes(sig, span)
+        attributes.set_trace_identity_attributes(node.span_context, span)
+        attributes.set_nt_schema_attributes(node.span_context, span)
+        span.set_attribute("narrative.duration_ms", node.duration_nanos / _NANOS_PER_MILLI)
+        attributes.set_outcome_attributes(node.outcome, span)
+        attributes.set_concurrency_attributes(node.concurrency, span)
+        if is_root:
+            attributes.set_trace_level_attributes(node.span_context, span)
+        self._export_children(node, span, walk)
+        span.end()
+
+    def _export_children(self, node: TraceNode, span: Span, walk: TreeWalk) -> None:
+        stop_reason = walk.stop_reason(node)
+        if stop_reason is not None:
+            if node.children:
+                span.set_attribute("narrative.truncated", _TRUNCATED_REASON[stop_reason])
+            return
+        walk.enter(node)
+        try:
+            with use_span(span, end_on_exit=False):
+                for child in node.children:
+                    attributes.emit_child_event(span, child)
+                    self._export_node(child, is_root=False, walk=walk)
+        finally:
+            walk.exit(node)

narrativetrace_otel-0.1.0/src/narrativetrace_otel/listener.py

@@ -0,0 +1,111 @@
+"""Live event-stream bridge from NarrativeTrace events to OpenTelemetry spans.
+
+``OtelTraceEventListener``. Plug this into the core pipeline as an event consumer to
+create spans as methods execute rather than after the whole tree is built. A
+:class:`~narrativetrace.pipeline.perishable.PerishableMap` of active spans is keyed by
+NarrativeTrace :class:`~narrativetrace.ids.SpanId`: an enter starts a span, the matching exit
+ends it. Orphaned spans (enter without exit) are evicted by the map's TTL/capacity limits and
+ended with :data:`~opentelemetry.trace.StatusCode.ERROR` description ``"orphaned"``.
+
+Parent-child links are reconstructed from explicit NarrativeTrace parent span ids, not from
+OTel's ambient context alone, so interleaved enter/exit pairs from concurrent traces resolve
+correctly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from opentelemetry.trace import Span, Status, StatusCode, Tracer, set_span_in_context
+
+from narrativetrace.events import EnterEvent, ExitEvent, TraceEvent
+from narrativetrace.pipeline.perishable import PerishableMap
+from narrativetrace_otel import attributes
+
+if TYPE_CHECKING:
+    from narrativetrace.ids import SpanId
+    from narrativetrace.signature import MethodSignature
+
+_DEFAULT_MAX_ACTIVE_SPANS = 1024
+_DEFAULT_TTL_SECONDS = 3600.0
+
+
+@dataclass(frozen=True, slots=True)
+class _SpanFrame:
+    """Pairs an OTel span with the signature captured at enter time."""
+
+    span: Span
+    signature: MethodSignature
+
+
+class OtelTraceEventListener:
+    """Consumes :class:`~narrativetrace.events.TraceEvent` and produces OTel spans live."""
+
+    def __init__(
+        self,
+        tracer: Tracer,
+        max_active_spans: int = _DEFAULT_MAX_ACTIVE_SPANS,
+        ttl_seconds: float = _DEFAULT_TTL_SECONDS,
+    ) -> None:
+        self._tracer = tracer
+        self._active_spans: PerishableMap[SpanId, _SpanFrame] = PerishableMap(
+            max_active_spans, ttl_seconds, lambda frame: _end_as_orphaned(frame.span)
+        )
+
+    def __call__(self, event: TraceEvent) -> None:
+        """Dispatches an event; non enter/exit events are ignored."""
+        if isinstance(event, EnterEvent):
+            self._handle_enter(event)
+        elif isinstance(event, ExitEvent):
+            self._handle_exit(event)
+
+    def _handle_enter(self, enter: EnterEvent) -> None:
+        sig = enter.signature
+        sc = enter.span_context
+        name = f"{sig.class_name}.{sig.method_name}"
+        parent_frame = (
+            self._active_spans.get(sc.parent_span_id) if sc.parent_span_id is not None else None
+        )
+        context = set_span_in_context(parent_frame.span) if parent_frame is not None else None
+        span = self._tracer.start_span(name, context=context, start_time=enter.timestamp_nanos)
+        attributes.set_span_attributes(sig, span)
+        attributes.set_trace_identity_attributes(sc, span)
+        attributes.set_nt_schema_attributes(sc, span)
+        if sc.parent_span_id is None:
+            attributes.set_trace_level_attributes(sc, span)
+        self._active_spans.put(sc.span_id, _SpanFrame(span, sig))
+
+    def _handle_exit(self, exit_event: ExitEvent) -> None:
+        frame = self._active_spans.remove(exit_event.span_context.span_id)
+        if frame is None:
+            self._handle_exit_without_enter(exit_event)
+            return
+        attributes.set_outcome_attributes(exit_event.outcome, frame.span)
+        frame.span.end(end_time=exit_event.timestamp_nanos)
+        self._emit_event_on_parent(exit_event, frame.signature)
+
+    def _emit_event_on_parent(self, exit_event: ExitEvent, sig: MethodSignature) -> None:
+        parent_span_id = exit_event.span_context.parent_span_id
+        if parent_span_id is None:
+            return
+        parent_frame = self._active_spans.get(parent_span_id)
+        if parent_frame is None:
+            return
+        attrs = attributes.build_event_attributes(sig, exit_event.outcome)
+        name = f"{sig.class_name}.{sig.method_name}"
+        parent_frame.span.add_event(name, attributes=attrs, timestamp=exit_event.timestamp_nanos)
+
+    def _handle_exit_without_enter(self, exit_event: ExitEvent) -> None:
+        sc = exit_event.span_context
+        span = self._tracer.start_span(str(sc.span_id), start_time=exit_event.timestamp_nanos)
+        attributes.set_trace_identity_attributes(sc, span)
+        attributes.set_trace_level_attributes(sc, span)
+        attributes.set_outcome_attributes(exit_event.outcome, span)
+        span.set_status(Status(StatusCode.ERROR, "orphaned — enter event lost"))
+        span.end(end_time=exit_event.timestamp_nanos)
+
+
+def _end_as_orphaned(span: Span) -> None:
+    span.set_status(Status(StatusCode.ERROR, "orphaned — exit event lost"))
+    span.end()

narrativetrace_otel-0.1.0/tests/conftest.py

@@ -0,0 +1,20 @@
+"""Shared fixtures: an in-memory OTel tracer capturing finished spans for assertions."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from otel_harness import Harness
+
+
+@pytest.fixture
+def otel() -> Iterator[Harness]:
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    yield Harness(provider.get_tracer("narrativetrace"), exporter)
+    provider.shutdown()