sonar-tracing-langchain 0.2.0__tar.gz

sonar_tracing_langchain-0.2.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+.env
+*.local.yaml
+.DS_Store
+
+# Collector persistent queue (runtime state)
+collector/queue/*
+!collector/queue/.gitkeep

sonar_tracing_langchain-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Ahmon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sonar_tracing_langchain-0.2.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: sonar-tracing-langchain
+Version: 0.2.0
+Summary: LangChain / LangGraph adapter for sonar-tracing.
+Author-email: Matthew Ahmon <matthew.ahmon@gmail.com>
+Maintainer-email: Matthew Ahmon <matthew.ahmon@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,langchain,langgraph,opentelemetry,sonar,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: openinference-instrumentation-langchain>=0.1
+Requires-Dist: sonar-tracing>=0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sonar-tracing-langchain
+
+LangChain / LangGraph adapter for [`sonar-tracing`](https://pypi.org/project/sonar-tracing/).
+
+Installing this package makes the `langchain` framework available to
+`sonar-tracing` — the adapter is discovered automatically via the
+`sonar_tracing.adapters` entry point group, so there's nothing to import or wire
+up by hand.
+
+```bash
+pip install sonar-tracing-langchain
+```
+
+```python
+import sonar_tracing as tracing
+
+tracing.init(service_name="support-agent", framework="langchain")
+```
+
+Unlike Strands, LangChain is not OpenTelemetry-native. This adapter installs the
+OpenInference `LangChainInstrumentor`, handing it the tracer provider
+`sonar-tracing` owns. The instrumentor patches `langchain-core`'s callback
+manager, so the same integration captures both LangChain and LangGraph — there
+is no separate LangGraph package to install.
+
+Spans are emitted under the OpenInference semantic conventions and normalised by
+the `openinference@1` mapping pack on the ingest side.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sonar_tracing_langchain-0.2.0/README.md

@@ -0,0 +1,31 @@
+# sonar-tracing-langchain
+
+LangChain / LangGraph adapter for [`sonar-tracing`](https://pypi.org/project/sonar-tracing/).
+
+Installing this package makes the `langchain` framework available to
+`sonar-tracing` — the adapter is discovered automatically via the
+`sonar_tracing.adapters` entry point group, so there's nothing to import or wire
+up by hand.
+
+```bash
+pip install sonar-tracing-langchain
+```
+
+```python
+import sonar_tracing as tracing
+
+tracing.init(service_name="support-agent", framework="langchain")
+```
+
+Unlike Strands, LangChain is not OpenTelemetry-native. This adapter installs the
+OpenInference `LangChainInstrumentor`, handing it the tracer provider
+`sonar-tracing` owns. The instrumentor patches `langchain-core`'s callback
+manager, so the same integration captures both LangChain and LangGraph — there
+is no separate LangGraph package to install.
+
+Spans are emitted under the OpenInference semantic conventions and normalised by
+the `openinference@1` mapping pack on the ingest side.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sonar_tracing_langchain-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "sonar-tracing-langchain"
+version = "0.2.0"
+description = "LangChain / LangGraph adapter for sonar-tracing."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Matthew Ahmon", email = "matthew.ahmon@gmail.com" }]
+maintainers = [{ name = "Matthew Ahmon", email = "matthew.ahmon@gmail.com" }]
+keywords = ["opentelemetry", "tracing", "langchain", "langgraph", "ai", "agents", "sonar"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = [
+    "sonar-tracing>=0.1",
+    "openinference-instrumentation-langchain>=0.1",
+    "langchain-core>=0.3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+# Discovered by sonar-tracing's registry via this entry point group. The adapter
+# module path is independent of sonar_tracing's package namespace.
+[project.entry-points."sonar_tracing.adapters"]
+langchain = "sonar_tracing_langchain:LangChainAdapter"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sonar_tracing_langchain"]

sonar_tracing_langchain-0.2.0/src/sonar_tracing_langchain/__init__.py

@@ -0,0 +1,98 @@
+"""LangChain / LangGraph adapter for sonar-tracing.
+
+LangChain is not OpenTelemetry-native. Tracing comes from a third-party
+instrumentor, ``openinference-instrumentation-langchain``, which patches
+``langchain-core``'s callback manager. Because LangGraph runs on the same
+``langchain-core`` foundation, one instrumentor covers both - there is no
+separate LangGraph adapter to write.
+
+This is the ``instrumentor`` shape (contrast the ``native`` Strands adapter):
+the real work is in ``attach()``, phase 2, because the instrumentor must be
+handed a live ``TracerProvider``. ``requirements()`` has nothing to pin - the
+instrumentor reads no environment configuration at import time - so it only
+stamps the framework version for provenance.
+
+Identity threading, redaction, sampling and OTLP export are all handled by core
+and are framework-agnostic; the OpenInference content keys are already covered
+by the default redaction patterns. Ingest normalises the emitted OpenInference
+attributes via the ``openinference@1`` mapping pack.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+
+from sonar_tracing.adapters.base import AttachContext, AttachResult, Requirements
+from sonar_tracing.semconv import FAMILY_OPENINFERENCE, SONAR_FRAMEWORK_VERSION
+
+__all__ = ["LangChainAdapter"]
+
+
+class LangChainAdapter:
+    name = "langchain"
+    semconv_family = FAMILY_OPENINFERENCE
+    mapping_pack = "openinference@1"
+
+    def __init__(self) -> None:
+        self._instrumentor: object | None = None
+
+    def detect(self) -> bool:
+        return importlib.util.find_spec("langchain_core") is not None
+
+    def requirements(self) -> Requirements:
+        resource: dict[str, str] = {}
+        version = _langchain_core_version()
+        if version:
+            resource[SONAR_FRAMEWORK_VERSION] = version
+        return Requirements(resource_attributes=resource)
+
+    def attach(self, ctx: AttachContext) -> AttachResult:
+        try:
+            from openinference.instrumentation.langchain import LangChainInstrumentor
+        except ImportError as exc:
+            return AttachResult(
+                ok=False,
+                mechanism="instrumentor",
+                detail=(
+                    "openinference-instrumentation-langchain is not installed; "
+                    f"cannot instrument LangChain ({exc})"
+                ),
+            )
+
+        instrumentor = LangChainInstrumentor()
+        instrumentor.instrument(tracer_provider=ctx.tracer_provider)
+        self._instrumentor = instrumentor
+
+        version = _langchain_core_version() or "unknown"
+        return AttachResult(
+            ok=True,
+            mechanism="instrumentor",
+            detail=(
+                f"langchain-core {version}: OpenInference LangChainInstrumentor installed; "
+                "covers LangChain and LangGraph via the shared callback manager"
+            ),
+            emitted_span_kinds=frozenset(
+                {"llm", "tool", "agent", "retrieval", "embedding", "chain"}
+            ),
+        )
+
+    def detach(self) -> None:
+        instrumentor = self._instrumentor
+        if instrumentor is None:
+            return
+        self._instrumentor = None
+        instrumentor.uninstrument()
+
+    def handles(self) -> list[object]:
+        # The instrumentor auto-patches langchain-core's callback manager, so
+        # LangGraph call sites need no hand-wired callback. Nothing to hand back.
+        return []
+
+
+def _langchain_core_version() -> str | None:
+    try:
+        from importlib.metadata import version
+
+        return version("langchain-core")
+    except Exception:  # noqa: BLE001
+        return None

sonar_tracing_langchain-0.2.0/tests/test_langchain_adapter.py

@@ -0,0 +1,110 @@
+"""The LangChain adapter, as its own package.
+
+The instrumentor is mocked: these tests pin the adapter's contract and its
+attach/detach behaviour without requiring a live LangChain runtime.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import sys
+import types
+
+import pytest
+from sonar_tracing.adapters.base import AttachContext
+from sonar_tracing.config import Settings
+from sonar_tracing.testing import assert_adapter_contract
+from sonar_tracing_langchain import LangChainAdapter
+
+
+class _FakeInstrumentor:
+    """Records the OpenTelemetry instrumentor lifecycle."""
+
+    last: _FakeInstrumentor | None = None
+
+    def __init__(self) -> None:
+        self.instrument_calls: list[object] = []
+        self.uninstrument_calls = 0
+        _FakeInstrumentor.last = self
+
+    def instrument(self, *, tracer_provider: object) -> None:
+        self.instrument_calls.append(tracer_provider)
+
+    def uninstrument(self) -> None:
+        self.uninstrument_calls += 1
+
+
+@pytest.fixture
+def fake_instrumentor(monkeypatch: pytest.MonkeyPatch) -> type[_FakeInstrumentor]:
+    """Install a fake ``openinference.instrumentation.langchain`` module."""
+    module = types.ModuleType("openinference.instrumentation.langchain")
+    module.LangChainInstrumentor = _FakeInstrumentor  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "openinference.instrumentation.langchain", module)
+    _FakeInstrumentor.last = None
+    return _FakeInstrumentor
+
+
+def _ctx() -> AttachContext:
+    provider = object()
+    return AttachContext(
+        tracer_provider=provider,  # type: ignore[arg-type]  # only passed through
+        settings=Settings(service_name="lc-test"),
+        logger=logging.getLogger("test"),
+    )
+
+
+def test_langchain_adapter_satisfies_the_contract() -> None:
+    assert_adapter_contract(LangChainAdapter())
+
+
+def test_attach_installs_the_openinference_instrumentor(
+    fake_instrumentor: type[_FakeInstrumentor],
+) -> None:
+    ctx = _ctx()
+    adapter = LangChainAdapter()
+    result = adapter.attach(ctx)
+
+    assert result.ok
+    assert result.mechanism == "instrumentor"
+    assert result.emitted_span_kinds  # non-empty
+    assert fake_instrumentor.last is not None
+    assert fake_instrumentor.last.instrument_calls == [ctx.tracer_provider]
+
+
+def test_detach_uninstruments_and_is_idempotent(
+    fake_instrumentor: type[_FakeInstrumentor],
+) -> None:
+    adapter = LangChainAdapter()
+
+    # Safe before any attach().
+    adapter.detach()
+
+    adapter.attach(_ctx())
+    instrumentor = fake_instrumentor.last
+    assert instrumentor is not None
+
+    adapter.detach()
+    adapter.detach()  # second call must not uninstrument again
+    assert instrumentor.uninstrument_calls == 1
+
+
+def test_attach_reports_failure_when_the_instrumentor_is_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """framework="langchain" loads the adapter regardless of detect(); a missing
+    instrumentor must degrade to ok=False, not raise."""
+    monkeypatch.setitem(sys.modules, "openinference.instrumentation.langchain", None)
+    result = LangChainAdapter().attach(_ctx())
+    assert result.ok is False
+    assert result.mechanism == "instrumentor"
+
+
+def test_requirements_pins_no_env_and_reports_a_version() -> None:
+    requirements = LangChainAdapter().requirements()
+    # Nothing to pin at import time - the instrumentor reads no env config.
+    assert requirements.env == {}
+    # When langchain-core is installed (a declared dependency), its version is
+    # stamped for provenance.
+    if importlib.util.find_spec("langchain_core") is not None:
+        assert "sonar.framework.version" in requirements.resource_attributes