insightfactory-databricks-langgraph-tracer 1.0.0.dev15__tar.gz → 1.0.1.dev18__tar.gz

{insightfactory_databricks_langgraph_tracer-1.0.0.dev15 → insightfactory_databricks_langgraph_tracer-1.0.1.dev18}/CHANGELOG.md

@@ -20,6 +20,56 @@ from this section.
 
 ## [Unreleased]
 
+### Added
+
+- `context_propagation` on `configure_databricks_tracing(...)` and on
+  `DatabricksLangGraphTracer(...)`, with the `DATABRICKS_TRACING_CONTEXT_PROPAGATION`
+  environment variable behind it. On by default; set it to `false`, `0`, `no` or
+  `off` to keep the previous behaviour, which also restores LangChain's default
+  callback dispatch.
+
+### Changed
+
+- The tracer's callbacks now run inline on the caller's thread while context
+  propagation is on, which on an async graph means the event loop. A
+  `content_ref_resolver` that blocks now blocks the loop rather than a worker
+  thread, so keep it fast.
+
+### Fixed
+
+- Spans created outside the tracer now nest under the running graph instead of
+  opening their own root trace (#52). A helper decorated with `@mlflow.trace`, or an
+  MLflow autolog integration, starts its span from MLflow's context, which the tracer
+  previously left empty; a consumer tracing its database helpers that way got one
+  extra root trace per query, none of them carrying the root tags, session metadata
+  or cost rollup. The tracer now publishes each live span into that context, and runs
+  its callbacks inline so the context reaches the code the node calls. Own-span
+  parenting is unchanged and still comes from LangChain's run tree, so concurrent
+  graph branches cannot cross-parent, and only the first tracer attached to a run
+  takes the context. Runs that overlap rather than nest, two `graph.stream()`
+  iterators consumed in start order, release their context in the order
+  OpenTelemetry requires: a run that ends while another is still stacked above it
+  holds its attach until that one ends, so a finished span is never restored over a
+  live one. Two limits come with that. A run whose end callback never fires pins the
+  attaches below it, which past a depth no real graph reaches is now reported at
+  warning. And another handler on the same run that also publishes to MLflow's
+  context, in practice `MlflowLangchainTracer` from `mlflow.langchain.autolog()`,
+  cannot be coordinated with: LangChain calls the two handlers' end hooks in
+  registration order, so whichever releases last restores an ended span. Two of
+  MLflow's own tracers on one run leak the same way with this tracer absent, so no
+  release order fixes it from inside one handler. The tracer warns once when it
+  detects the conflict and names both settings to turn off. Issue #57 tracks it.
+
+## [1.0.1] - 2026-09-03
+
+### Changed
+
+- Rewrote the README that PyPI renders in plainer prose. Commands, code samples
+  and configuration tables are unchanged, so there is no behaviour or packaging
+  change.
+- Corrected the truncation placeholder example, which showed a trailing ellipsis
+  in `preview`. The tracer stores a plain slice of the original string.
+
 ## [1.0.0] - 2026-09-01
 ### Changed
 - Renamed the PyPI distribution from `databricks-langgraph-tracer` to
@@ -163,7 +213,8 @@ reserved by the repo's immutable-releases policy and cannot be created. Restore
 python-vX.Y.Z tag links if the names are ever reclaimed. 0.5.0's tag is created
 out-of-band (its bump predates the release workflow); 0.5.1+ tags are minted by
 release.yml on push to main. -->
-[Unreleased]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/python-v1.0.0...HEAD
+[Unreleased]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/python-v1.0.1...HEAD
+[1.0.1]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/python-v1.0.0...python-v1.0.1
 [1.0.0]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/python-v0.6.1...python-v1.0.0
 [0.6.1]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/python-v0.6.0...python-v0.6.1
 [0.6.0]: https://github.com/insightfactory-ai/if_s_langraph_mlflow_tracer/compare/python-v0.5.0...python-v0.6.0

{insightfactory_databricks_langgraph_tracer-1.0.0.dev15 → insightfactory_databricks_langgraph_tracer-1.0.1.dev18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: insightfactory-databricks-langgraph-tracer
-Version: 1.0.0.dev15
+Version: 1.0.1.dev18
 Summary: LangGraph tracing for Databricks MLflow
 Project-URL: Homepage, https://insightfactory.ai
 Author-email: "insightfactory.ai" <support@insightfactory.ai>
@@ -71,6 +71,7 @@ overrides the matching variable.
 | Source tag | none | `source=` kwarg, default `langgraph` |
 | Multimodal refs | none | Inline image, PDF and file bytes become a reference. `content_ref_resolver=` chooses it. See below. |
 | Text cap | `DATABRICKS_TRACING_MAX_STRING_CHARS` | Opt-in. `max_string_chars=` truncates long plain-text span content. See below. |
+| Context propagation | `DATABRICKS_TRACING_CONTEXT_PROPAGATION` | On by default. Set to `false`, `0`, `no` or `off`, or pass `context_propagation=False`, to stop publishing spans into MLflow's context. See below. |
 | Disable | `TESTING` or `BUILDING` set to `true`, or `enabled=False` | Turns the tracer into a no-op. This is the only path that does not raise. |
 | UC-backed tracing | `MLFLOW_TRACING_UC_BACKED=true` or `uc_tracing=True` | See below. |
 | SQL warehouse | `MLFLOW_TRACING_SQL_WAREHOUSE_ID`, falling back to `DATABRICKS_WAREHOUSE_ID` | Required when UC-backed. |
@@ -192,6 +193,80 @@ bytes, and multibyte text can be up to four times larger in bytes than in charac
 CJK or emoji-heavy content size the cap below a quarter of the limit. The placeholder's
 `bytes` field always reports the exact UTF-8 size of the original.
 
+### Spans from outside the tracer
+
+A helper decorated with `@mlflow.trace`, or an MLflow autolog integration, starts its
+span through MLflow's context rather than through LangChain's callbacks. The tracer
+publishes each live span into that context, so those spans nest under whichever node is
+running instead of opening a root trace of their own:
+
+```python
+import mlflow
+
+@mlflow.trace(span_type="TOOL", name="lakebase.execute_query")
+def execute_query(sql: str): ...
+```
+
+Calling that from a graph node produces one trace, with the tool span parented to the
+node. Without it you get a second root trace per call, carrying none of the root tags,
+session metadata or cost rollup the tracer writes.
+
+Attaching the context requires the tracer's callbacks to run in the caller's own
+context, so `run_inline` is set on the handler whenever propagation is on. Only
+LangChain's async callback manager reads that flag: without it an async run sends the
+handler through an executor with a copied context, which the node body never sees. The
+sync manager calls handlers in the caller's thread either way.
+
+The tracer still parents its own spans from LangChain's run tree, never from the
+context, so concurrent branches of a graph cannot cross-parent. Runs that overlap
+rather than nest, two `stream(...)` generators created before either is consumed,
+release their attaches in the order OpenTelemetry requires: a run that ends while
+another is still stacked above it holds its attach until that one ends, so a finished
+span is never restored over a live one.
+
+The price of never releasing out of order is that a run whose end callback never
+fires pins the attaches beneath it. A node that abandons an inner `stream(...)`
+part-consumed leaves its span active for the life of that context, and spans started
+there parent to a run that has already finished. Sweeping the stack when the
+outermost run ends would clear it and bring back the overlapping-run bug above, so
+the tracer reports it instead: past a depth no real graph reaches, it logs a warning
+naming the count.
+
+Only one handler attaches per run. Attach a second context-propagating tracer to the
+same graph and it records its own spans as before, but leaves the context to the
+first.
+
+Three limits are worth knowing:
+
+- It only works in one direction. A root run is always created without a parent and
+  without consulting the context, so a graph invoked from *inside* an `@mlflow.trace`
+  function still opens its own root trace rather than nesting into the caller's. This
+  is the one place the TypeScript package behaves differently: MLflow's JavaScript
+  `startSpan` falls back to the active context, so a graph there does nest into an
+  enclosing span.
+- Foreign spans are recorded by MLflow, not by this tracer, so neither the text cap
+  nor the multimodal reference substitution applies to them. A traced query helper
+  returning a large rowset can push a trace back over the inline read limit that
+  `max_string_chars` was set to stay under.
+- The tracer's callbacks run inline on the caller's thread, which on an async graph
+  means the event loop. Keep `content_ref_resolver` fast and non-blocking.
+- Another handler on the same run that also publishes to MLflow's context, which in
+  practice means `MlflowLangchainTracer` from `mlflow.langchain.autolog()`, cannot be
+  coordinated with. LangChain calls the two handlers' end hooks in registration order,
+  so the attaches nest but the releases run front to back, and whichever releases last
+  restores an ended span. Two of MLflow's own tracers on one run leak the same way
+  with this tracer absent, so no release order fixes it here. The tracer warns once
+  when it detects the conflict and names both settings to turn off; turn one of them
+  off. Issue #57 tracks it.
+
+To turn the whole behaviour off, pass `context_propagation=False` or set
+`DATABRICKS_TRACING_CONTEXT_PROPAGATION=false` (`0`, `no` and `off` also work). That
+also restores LangChain's default callback dispatch.
+
+The TypeScript package reaches the same outcome through `getActiveTracingSpan()` and
+`withTracingContext()`, named at the call site, because Node has no ambient
+equivalent. See [`../typescript/README.md`](../typescript/README.md).
+
 ### Autolog fallback
 
 `mode="autolog"` wires MLflow's built-in LangChain autologging plus compatibility patches. It

{insightfactory_databricks_langgraph_tracer-1.0.0.dev15 → insightfactory_databricks_langgraph_tracer-1.0.1.dev18}/README.md

@@ -47,6 +47,7 @@ overrides the matching variable.
 | Source tag | none | `source=` kwarg, default `langgraph` |
 | Multimodal refs | none | Inline image, PDF and file bytes become a reference. `content_ref_resolver=` chooses it. See below. |
 | Text cap | `DATABRICKS_TRACING_MAX_STRING_CHARS` | Opt-in. `max_string_chars=` truncates long plain-text span content. See below. |
+| Context propagation | `DATABRICKS_TRACING_CONTEXT_PROPAGATION` | On by default. Set to `false`, `0`, `no` or `off`, or pass `context_propagation=False`, to stop publishing spans into MLflow's context. See below. |
 | Disable | `TESTING` or `BUILDING` set to `true`, or `enabled=False` | Turns the tracer into a no-op. This is the only path that does not raise. |
 | UC-backed tracing | `MLFLOW_TRACING_UC_BACKED=true` or `uc_tracing=True` | See below. |
 | SQL warehouse | `MLFLOW_TRACING_SQL_WAREHOUSE_ID`, falling back to `DATABRICKS_WAREHOUSE_ID` | Required when UC-backed. |
@@ -168,6 +169,80 @@ bytes, and multibyte text can be up to four times larger in bytes than in charac
 CJK or emoji-heavy content size the cap below a quarter of the limit. The placeholder's
 `bytes` field always reports the exact UTF-8 size of the original.
 
+### Spans from outside the tracer
+
+A helper decorated with `@mlflow.trace`, or an MLflow autolog integration, starts its
+span through MLflow's context rather than through LangChain's callbacks. The tracer
+publishes each live span into that context, so those spans nest under whichever node is
+running instead of opening a root trace of their own:
+
+```python
+import mlflow
+
+@mlflow.trace(span_type="TOOL", name="lakebase.execute_query")
+def execute_query(sql: str): ...
+```
+
+Calling that from a graph node produces one trace, with the tool span parented to the
+node. Without it you get a second root trace per call, carrying none of the root tags,
+session metadata or cost rollup the tracer writes.
+
+Attaching the context requires the tracer's callbacks to run in the caller's own
+context, so `run_inline` is set on the handler whenever propagation is on. Only
+LangChain's async callback manager reads that flag: without it an async run sends the
+handler through an executor with a copied context, which the node body never sees. The
+sync manager calls handlers in the caller's thread either way.
+
+The tracer still parents its own spans from LangChain's run tree, never from the
+context, so concurrent branches of a graph cannot cross-parent. Runs that overlap
+rather than nest, two `stream(...)` generators created before either is consumed,
+release their attaches in the order OpenTelemetry requires: a run that ends while
+another is still stacked above it holds its attach until that one ends, so a finished
+span is never restored over a live one.
+
+The price of never releasing out of order is that a run whose end callback never
+fires pins the attaches beneath it. A node that abandons an inner `stream(...)`
+part-consumed leaves its span active for the life of that context, and spans started
+there parent to a run that has already finished. Sweeping the stack when the
+outermost run ends would clear it and bring back the overlapping-run bug above, so
+the tracer reports it instead: past a depth no real graph reaches, it logs a warning
+naming the count.
+
+Only one handler attaches per run. Attach a second context-propagating tracer to the
+same graph and it records its own spans as before, but leaves the context to the
+first.
+
+Three limits are worth knowing:
+
+- It only works in one direction. A root run is always created without a parent and
+  without consulting the context, so a graph invoked from *inside* an `@mlflow.trace`
+  function still opens its own root trace rather than nesting into the caller's. This
+  is the one place the TypeScript package behaves differently: MLflow's JavaScript
+  `startSpan` falls back to the active context, so a graph there does nest into an
+  enclosing span.
+- Foreign spans are recorded by MLflow, not by this tracer, so neither the text cap
+  nor the multimodal reference substitution applies to them. A traced query helper
+  returning a large rowset can push a trace back over the inline read limit that
+  `max_string_chars` was set to stay under.
+- The tracer's callbacks run inline on the caller's thread, which on an async graph
+  means the event loop. Keep `content_ref_resolver` fast and non-blocking.
+- Another handler on the same run that also publishes to MLflow's context, which in
+  practice means `MlflowLangchainTracer` from `mlflow.langchain.autolog()`, cannot be
+  coordinated with. LangChain calls the two handlers' end hooks in registration order,
+  so the attaches nest but the releases run front to back, and whichever releases last
+  restores an ended span. Two of MLflow's own tracers on one run leak the same way
+  with this tracer absent, so no release order fixes it here. The tracer warns once
+  when it detects the conflict and names both settings to turn off; turn one of them
+  off. Issue #57 tracks it.
+
+To turn the whole behaviour off, pass `context_propagation=False` or set
+`DATABRICKS_TRACING_CONTEXT_PROPAGATION=false` (`0`, `no` and `off` also work). That
+also restores LangChain's default callback dispatch.
+
+The TypeScript package reaches the same outcome through `getActiveTracingSpan()` and
+`withTracingContext()`, named at the call site, because Node has no ambient
+equivalent. See [`../typescript/README.md`](../typescript/README.md).
+
 ### Autolog fallback
 
 `mode="autolog"` wires MLflow's built-in LangChain autologging plus compatibility patches. It

{insightfactory_databricks_langgraph_tracer-1.0.0.dev15 → insightfactory_databricks_langgraph_tracer-1.0.1.dev18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "insightfactory-databricks-langgraph-tracer"
-version = "1.0.0.dev15"
+version = "1.0.1.dev18"
 description = "LangGraph tracing for Databricks MLflow"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{insightfactory_databricks_langgraph_tracer-1.0.0.dev15 → insightfactory_databricks_langgraph_tracer-1.0.1.dev18}/src/databricks_langgraph_tracer/mlflow_utils.py

@@ -161,6 +161,7 @@ def configure_databricks_tracing(
     sql_warehouse_id: str | None = None,
     content_ref_resolver: "ContentRefResolver | None" = None,
     max_string_chars: int | None = None,
+    context_propagation: bool | None = None,
 ) -> TracingConfiguration:
     """Bootstrap Databricks MLflow tracing and return the active configuration.
 
@@ -178,6 +179,19 @@ def configure_databricks_tracing(
     not just multimodal bytes, can push a trace past the SQL inline read limit);
     falls back to ``DATABRICKS_TRACING_MAX_STRING_CHARS``, else off. Like the
     resolver, it applies only under ``mode="tracer"``.
+
+    ``context_propagation`` (default on) publishes each live span into MLflow's
+    context, so spans started outside this tracer — an ``@mlflow.trace``-decorated
+    helper, an MLflow autolog integration — nest under the running graph instead of
+    opening their own root trace (issue #52); falls back to
+    ``DATABRICKS_TRACING_CONTEXT_PROPAGATION``, which turns it off for ``false`` /
+    ``0`` / ``no`` / ``off`` (case-insensitive) and is otherwise ignored.
+
+    ``mode`` picks between two alternatives, never both: ``"tracer"`` (the default)
+    attaches this package's ``BaseTracer`` for the full shared schema, while
+    ``"autolog"`` installs MLflow's LangChain autologging and attaches no callback.
+    The three options above shape only the ``"tracer"`` path. Autolog already traces
+    through MLflow's own context, so it needs no propagation.
     """
     global _bootstrap_done, _active_config
     # explicit disable path (design Decision 3): enabled=False OR skip-guard -> no-op
@@ -300,6 +314,7 @@ def configure_databricks_tracing(
                 source=source,
                 content_ref_resolver=content_ref_resolver,
                 max_string_chars=max_string_chars,
+                context_propagation=context_propagation,
             )
         ]
     _active_config = TracingConfiguration(

{insightfactory_databricks_langgraph_tracer-1.0.0.dev15 → insightfactory_databricks_langgraph_tracer-1.0.1.dev18}/src/databricks_langgraph_tracer/tracer.py

@@ -55,7 +55,9 @@ import logging
 import math
 import os
 from collections.abc import Callable
+from contextvars import ContextVar
 from dataclasses import dataclass
+from typing import Any
 
 import mlflow
 from langchain_core.tracers.base import BaseTracer
@@ -84,6 +86,23 @@ from .cost import (
     qualify_deployment_name,
 )
 
+# OpenTelemetry context propagation (issue #52). These live on a private MLflow
+# module path, so the import is guarded: a future relocation degrades to "no context
+# propagation" rather than breaking every consumer's import of this package. The
+# names are annotated up front so both branches share one optional type. The attach
+# token is an MLflow-internal union (a contextvars Token, or a pair of them), so it
+# is carried as Any rather than restated here.
+_set_span_in_context: "Callable[[LiveSpan], Any] | None"
+_detach_span_from_context: "Callable[[Any], Any] | None"
+try:
+    from mlflow.tracing.provider import detach_span_from_context, set_span_in_context
+
+    _set_span_in_context = set_span_in_context
+    _detach_span_from_context = detach_span_from_context
+except ImportError:  # pragma: no cover - depends on the installed mlflow layout
+    _set_span_in_context = None
+    _detach_span_from_context = None
+
 logger = logging.getLogger(__name__)
 
 # Pydantic BaseModel classes whose models MLflow expands when serializing. Both v2
@@ -160,6 +179,88 @@ def _resolve_max_string_chars(explicit: int | None) -> int | None:
     return value if value > 0 else None
 
 
+# ---------------------------------------------------------------------------
+# OpenTelemetry context propagation (issue #52).
+#
+# Spans are created with ``mlflow.start_span_no_context`` and parented explicitly
+# from ``_span_map``, which keeps LangChain's callback tree authoritative and makes
+# the tracer immune to context leaking between concurrent graph runs. The cost is
+# that MLflow's *own* context is never populated, so a span started by anything
+# other than this tracer — an ``@mlflow.trace`` tool, an MLflow autolog integration
+# — finds no active parent and opens a second root trace. A consumer tracing its
+# database helpers that way gets one trace per query alongside the graph trace,
+# none of them carrying the root tags or the cost rollup.
+#
+# Publishing each live span into MLflow's context closes that gap: the tracer still
+# parents its own spans from ``_span_map``, and everything else nests under whichever
+# span is active. The attach token is detached in ``_end_trace``'s finally block, so
+# a failure anywhere in span finalization cannot leak it.
+#
+# The attaches live in this context, innermost last. Two things make a plain
+# attach-here / release-there pair wrong, and both were observed:
+#
+# 1. Two context-propagating tracers on one run. LangChain invokes every handler in
+#    registration order, so both attach and both release front-to-back, and the
+#    second release restores the context from before the *first* attach, leaving the
+#    first tracer's already-ended span active.
+# 2. Runs that overlap rather than nest. Two ``graph.stream()`` iterators started
+#    before either is consumed end in consumption order, so the releases again run
+#    front-to-back and the finished run's span is restored over the live one.
+#
+# Either way a later ``@mlflow.trace`` call joins a finalized trace. This stack fixes
+# both: a run already on it never attaches twice, and a run that ends out of order is
+# only marked, with its token released once every attach above it has ended. Releases
+# therefore always run innermost-first, which is the order OpenTelemetry requires.
+# Entries are replaced rather than reset, so a token never has to be valid in the
+# context that releases it.
+#
+# The price of never releasing out of order is head-of-line blocking: a run whose
+# ``_end_trace`` never fires pins every attach beneath it, because the drain loop
+# stops at the first entry that has not ended. A node that abandons an inner
+# ``stream(...)`` part-consumed, or a generator finalized by the garbage collector in
+# some other context, leaves its span active for the life of that context. Sweeping
+# the stack when the bottom entry ends would fix that and reintroduce case 2, so the
+# blocking is the deliberate trade. ``_MAX_ATTACHMENT_DEPTH`` makes it diagnosable.
+@dataclass(frozen=True)
+class _Attachment:
+    """One live context attach: the run that owns it and the token that releases it."""
+
+    run_id: str
+    span_id: str
+    token: Any
+    ended: bool = False
+
+
+_attachments: ContextVar[tuple[_Attachment, ...]] = ContextVar(
+    "databricks_tracer_attachments", default=()
+)
+
+# Depth at which the stack is reported as stuck rather than deep. A graph nests a few
+# runs, not dozens, so anything past this is a run that never ended pinning the ones
+# below it (see the head-of-line note above) rather than genuine depth.
+_MAX_ATTACHMENT_DEPTH = 64
+
+_CONTEXT_PROPAGATION_ENV = "DATABRICKS_TRACING_CONTEXT_PROPAGATION"
+# Opt-*out* polarity, so this cannot reuse the ``== "true"`` idiom the other boolean
+# env vars in this package use (see mlflow_utils).
+_CONTEXT_PROPAGATION_FALSE_VALUES = frozenset({"false", "0", "no", "off"})
+
+
+def _resolve_context_propagation(explicit: bool | None) -> bool:
+    """Resolve context propagation: explicit arg wins, else the env var, else on.
+
+    Only an explicit false-y value ("false" / "0" / "no" / "off", case-insensitive)
+    turns it off, so an unset, empty or unrecognized variable leaves the default in
+    place. Matches ``_resolve_max_string_chars``, which also ignores an empty value.
+    """
+    if explicit is not None:
+        return explicit
+    raw = os.getenv(_CONTEXT_PROPAGATION_ENV)
+    if not raw:
+        return True
+    return raw.strip().lower() not in _CONTEXT_PROPAGATION_FALSE_VALUES
+
+
 def _truncate_long_string(value: str, max_string_chars: int | None):
     """Replace an over-cap string leaf with a compact placeholder; else return it as-is.
 
@@ -703,6 +804,7 @@ class DatabricksLangGraphTracer(BaseTracer):
         source: str = "langgraph",
         content_ref_resolver: ContentRefResolver | None = None,
         max_string_chars: int | None = None,
+        context_propagation: bool | None = None,
         **kw,
     ):
         # ``content_ref_resolver`` maps each multimodal content part to the reference
@@ -729,7 +831,39 @@ class DatabricksLangGraphTracer(BaseTracer):
         self._source = source
         self._content_ref_resolver = content_ref_resolver
         self._max_string_chars = _resolve_max_string_chars(max_string_chars)
+        # ``context_propagation`` publishes each live span into MLflow's context so
+        # spans started outside this tracer (an ``@mlflow.trace`` tool, an autolog
+        # integration) nest under the graph instead of opening their own root trace
+        # (issue #52); falls back to DATABRICKS_TRACING_CONTEXT_PROPAGATION, else on.
+        # Forced off when the MLflow context helpers are unavailable.
+        self._context_propagation = _resolve_context_propagation(
+            context_propagation
+        ) and (
+            _set_span_in_context is not None and _detach_span_from_context is not None
+        )
+        # Only the *async* callback manager consults run_inline: a sync handler that
+        # does not set it is dispatched through run_in_executor with a copied context,
+        # so an attach inside it never reaches the node body. langchain-core 1.x
+        # defaults BaseTracer to False, which is why the async path needs this. The
+        # sync manager calls handlers in the caller's thread either way (verified
+        # against langchain-core 1.6). Set per instance, matching autolog_compat, so
+        # opting out of context propagation also opts out of the dispatch change.
+        #
+        # Inline means this handler runs on the event loop rather than a worker
+        # thread. It only manipulates in-memory span state, but it also walks the
+        # payload for _externalize_content_refs and calls the consumer's
+        # content_ref_resolver — which must therefore be fast and non-blocking.
+        self.run_inline = self._context_propagation
         self._span_map: dict[str, LiveSpan] = {}
+        # Runs this tracer attached to the context. The tokens themselves live on the
+        # _attachments stack; this only records which entries are ours to end, so a
+        # second tracer on the same run does not end the first one's attach. Named
+        # apart from the stack on purpose: this one is instance-local, the stack is
+        # context-local and shared across tracers.
+        self._runs_i_attached: set[str] = set()
+        # One warning per tracer for each of the two context hazards.
+        self._warned_shared_context = False
+        self._warned_stack_depth = False
         # Per-root cost accumulators, keyed by root run id.
         self._aggregates: dict[str, TraceAggregate] = {}
         # Run id to root run id, so child LLM spans find their root.
@@ -766,6 +900,7 @@ class DatabricksLangGraphTracer(BaseTracer):
                 inputs=inputs,
             )
             self._span_map[str(run.id)] = span
+            self._attach_context(run, span)
             if run.parent_run_id is None:  # ROOT
                 self._aggregates[str(run.id)] = TraceAggregate(
                     root_trace_id=span.trace_id
@@ -836,12 +971,127 @@ class DatabricksLangGraphTracer(BaseTracer):
                 except Exception:
                     logger.debug("span end failed", exc_info=True)
         finally:
+            # Detach after every span write, so the context unwinds in the reverse
+            # order it was attached (child before parent) and a failure above still
+            # releases it.
+            self._detach_context(run)
             # Unconditionally clear this run's root mapping (self-map for a root,
             # own->root lookup for a child). Never delete the *value*: sibling
             # children of a still-running root rely on its self-mapping.
             self._root_by_run.pop(str(run.id), None)
             super()._end_trace(run)
 
+    def _attach_context(self, run: Run, span: LiveSpan) -> None:
+        """Publish ``span`` into MLflow's context as the active span (issue #52).
+
+        Pushes the release token onto the context-local stack and records the run id on
+        this tracer, which is what marks the entry as this tracer's to end. A failure is
+        logged and swallowed: losing context propagation degrades nesting for foreign
+        spans, it must never break the trace this tracer is recording.
+        """
+        if not self._context_propagation or _set_span_in_context is None:
+            return
+        run_id = str(run.id)
+        stack = _attachments.get()
+        if any(entry.run_id == run_id for entry in stack):
+            return  # another handler on this run already owns the attach
+        try:
+            token = _set_span_in_context(span)
+        except Exception:
+            logger.debug("attach span context failed", exc_info=True)
+            return
+        # Pushed only after the attach succeeds, so a failure here leaves the next
+        # handler free to try rather than suppressing it for a token that never was.
+        entries = (*stack, _Attachment(run_id, span.span_id, token))
+        _attachments.set(entries)
+        self._runs_i_attached.add(run_id)
+        if len(entries) > _MAX_ATTACHMENT_DEPTH and not self._warned_stack_depth:
+            self._warned_stack_depth = True
+            logger.warning(
+                "%d spans are attached to MLflow's context in this context, which "
+                "means a run ended without its end callback firing and is holding "
+                "the attaches below it. Spans started here will parent to a run that "
+                "has already finished.",
+                len(entries),
+            )
+
+    def _detach_context(self, run: Run) -> None:
+        """Mark this run's attach as ended and release every attach now on top.
+
+        An attach can only be released once nothing is stacked above it, so a run
+        that ends out of order is marked and left in place; its token goes when the
+        run above it ends. That keeps the releases innermost-first, which is what
+        OpenTelemetry's token contract requires, and it never restores an ended span
+        over a live one.
+
+        A failed release is logged at warning, unlike a failed attach: a failed attach
+        costs nesting for one run, while a failed release leaves an *ended* span active
+        in a context that outlives the run (a reused server thread, a long-lived event
+        loop), so later spans in that context would parent to a finalized span.
+        OpenTelemetry's own ``detach`` swallows most mismatches and logs them itself,
+        so this is a backstop rather than the only signal.
+        """
+        run_id = str(run.id)
+        if run_id not in self._runs_i_attached:
+            return
+        # Discarded first, so a failure below cannot leave the run looking attached.
+        self._runs_i_attached.discard(run_id)
+        if _detach_span_from_context is None:
+            return
+        entries = list(_attachments.get())
+        index = next(
+            (i for i, entry in enumerate(entries) if entry.run_id == run_id), None
+        )
+        if index is None:
+            # Attached in a different context than the one ending the run, so this
+            # context has nothing to release. The attach's own context still holds the
+            # token and unwinds normally when it is discarded.
+            return
+        self._warn_if_context_shared(entries)
+        entries[index] = dataclasses.replace(entries[index], ended=True)
+        while entries and entries[-1].ended:
+            entry = entries.pop()
+            try:
+                _detach_span_from_context(entry.token)
+            except Exception:
+                logger.warning("detach span context failed", exc_info=True)
+        _attachments.set(tuple(entries))
+
+    def _warn_if_context_shared(self, entries: list[_Attachment]) -> None:
+        """Warn once if another context publisher has attached above this tracer.
+
+        The stack this tracer keeps only covers its own attaches. Another handler on
+        the same run that also publishes to MLflow's context, ``MlflowLangchainTracer``
+        from ``mlflow.langchain.autolog()`` being the one in practice, attaches its own
+        token, and LangChain calls the two handlers' end hooks in registration order.
+        Whichever releases last restores the span it recorded at attach time, which is
+        by then an ended span, so a later ``@mlflow.trace`` call joins a finalized
+        trace.
+
+        No release order fixes this from inside one handler, and it is not specific to
+        this tracer: two ``MlflowLangchainTracer`` instances on one run leak the same
+        way with this tracer absent. MLflow's own answer is the global
+        ``_should_attach_span_to_context`` opt-out rather than a coordination protocol.
+        So this warns rather than repairs, and names the setting to turn off. Issue #57.
+
+        An enclosing span the caller opened around the graph is not this case: it sits
+        *below* this tracer's attaches, so the stack top still matches.
+        """
+        if self._warned_shared_context or not entries:
+            return
+        active = mlflow.get_current_active_span()
+        if active is not None and active.span_id == entries[-1].span_id:
+            return
+        self._warned_shared_context = True
+        logger.warning(
+            "another handler has attached a span to MLflow's context inside this run, "
+            "so the context cannot unwind in order and a span started after the run "
+            "may join a finalized trace. Disable context propagation on one of them: "
+            "%s=false for this tracer, or mlflow.langchain.autolog(log_traces=False) "
+            "for MLflow's own LangChain tracer.",
+            _CONTEXT_PROPAGATION_ENV,
+        )
+
     def _write_root_trace_fields(self, run: Run, span: LiveSpan) -> None:
         """Write the root trace tags and session/user metadata.