sonar-tracing 0.1.0__tar.gz

sonar_tracing-0.1.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-0.1.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-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: sonar-tracing
+Version: 0.1.0
+Summary: One-line OpenTelemetry tracing for AI agents, across frameworks.
+Project-URL: Homepage, https://github.com/deep-dive-mexico/sonar
+Project-URL: Repository, https://github.com/deep-dive-mexico/sonar
+Project-URL: Issues, https://github.com/deep-dive-mexico/sonar/issues
+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,llm,observability,opentelemetry,otel,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: opentelemetry-api>=1.30
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30
+Requires-Dist: opentelemetry-sdk>=1.30
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sonar-tracing
+
+One-line OpenTelemetry tracing for AI agents, across frameworks.
+
+```python
+import sonar_tracing as tracing
+
+tracing.init(service_name="support-agent", framework="strands")
+
+with tracing.identity(tenant_id="acme", session_id=session_id):
+    result = agent(prompt)
+```
+
+That is the whole integration. No exporter wiring, no `TracerProvider`, no OTLP
+setup — `init()` builds the production processor/exporter chain for you and
+`identity()` stamps tenant/session context onto every span in scope.
+
+## Install
+
+```bash
+pip install sonar-tracing
+```
+
+Framework support ships as a separate package. For AWS Strands, also install the
+adapter — it registers itself, so there is nothing to import:
+
+```bash
+pip install sonar-tracing sonar-tracing-strands
+```
+
+## What it does
+
+- **`init()`** — stands up a `TracerProvider` wired to an OTLP HTTP exporter,
+  with redaction and identity-stamping built into the pipeline.
+- **`identity()`** — a context manager that attaches tenant/session attributes
+  to spans created within it.
+- **Framework support is a plugin, not a branch.** Adapters are discovered from
+  the `sonar_tracing.adapters` entry point group, so a new framework ships as a
+  new package — core never changes.
+
+## Requirements
+
+- Python 3.11+
+- An OTLP-compatible collector endpoint
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sonar_tracing-0.1.0/README.md

@@ -0,0 +1,48 @@
+# sonar-tracing
+
+One-line OpenTelemetry tracing for AI agents, across frameworks.
+
+```python
+import sonar_tracing as tracing
+
+tracing.init(service_name="support-agent", framework="strands")
+
+with tracing.identity(tenant_id="acme", session_id=session_id):
+    result = agent(prompt)
+```
+
+That is the whole integration. No exporter wiring, no `TracerProvider`, no OTLP
+setup — `init()` builds the production processor/exporter chain for you and
+`identity()` stamps tenant/session context onto every span in scope.
+
+## Install
+
+```bash
+pip install sonar-tracing
+```
+
+Framework support ships as a separate package. For AWS Strands, also install the
+adapter — it registers itself, so there is nothing to import:
+
+```bash
+pip install sonar-tracing sonar-tracing-strands
+```
+
+## What it does
+
+- **`init()`** — stands up a `TracerProvider` wired to an OTLP HTTP exporter,
+  with redaction and identity-stamping built into the pipeline.
+- **`identity()`** — a context manager that attaches tenant/session attributes
+  to spans created within it.
+- **Framework support is a plugin, not a branch.** Adapters are discovered from
+  the `sonar_tracing.adapters` entry point group, so a new framework ships as a
+  new package — core never changes.
+
+## Requirements
+
+- Python 3.11+
+- An OTLP-compatible collector endpoint
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sonar_tracing-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "sonar-tracing"
+dynamic = ["version"]
+description = "One-line OpenTelemetry tracing for AI agents, across frameworks."
+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", "observability", "ai", "agents", "llm", "otel"]
+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 = [
+    "opentelemetry-api>=1.30",
+    "opentelemetry-sdk>=1.30",
+    "opentelemetry-exporter-otlp-proto-http>=1.30",
+]
+
+[project.urls]
+Homepage = "https://github.com/deep-dive-mexico/sonar"
+Repository = "https://github.com/deep-dive-mexico/sonar"
+Issues = "https://github.com/deep-dive-mexico/sonar/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/sonar_tracing/version.py"
+
+[tool.hatch.build.targets.wheel]
+# testing/ ships: it's the public adapter-contract helper (assert_adapter_contract,
+# build_pipeline) that third-party adapter authors import to verify their adapter.
+packages = ["src/sonar_tracing"]

sonar_tracing-0.1.0/src/sonar_tracing/__init__.py

@@ -0,0 +1,35 @@
+"""sonar-tracing - unified OpenTelemetry tracing for AI agents.
+
+import sonar_tracing as tracing
+
+tracing.init(service_name="support-agent", framework="strands")
+
+with tracing.identity(tenant_id="acme", session_id=session):
+    result = agent(prompt)
+"""
+
+from .bootstrap import (
+    TracingState,
+    current_state,
+    force_flush,
+    handles,
+    init,
+    shutdown,
+)
+from .context import Identity, current_identity, identity
+from .safety import diagnostics
+from .version import __version__
+
+__all__ = [
+    "Identity",
+    "TracingState",
+    "__version__",
+    "current_identity",
+    "current_state",
+    "diagnostics",
+    "force_flush",
+    "handles",
+    "identity",
+    "init",
+    "shutdown",
+]

sonar_tracing-0.1.0/src/sonar_tracing/adapters/__init__.py

@@ -0,0 +1,10 @@
+from .base import Adapter, AttachContext, AttachResult, BaseAdapter, Requirements, validate_adapter
+
+__all__ = [
+    "Adapter",
+    "AttachContext",
+    "AttachResult",
+    "BaseAdapter",
+    "Requirements",
+    "validate_adapter",
+]

sonar_tracing-0.1.0/src/sonar_tracing/adapters/base.py

@@ -0,0 +1,135 @@
+"""The adapter contract.
+
+Frameworks integrate with OpenTelemetry in at least four different shapes:
+
+  native        the framework is OTel-aware and only needs a global provider
+                to exist (Strands)
+  instrumentor  a third-party package monkey-patches the framework and needs
+                the provider to already exist (LangChain via OpenInference)
+  processor     the framework has its own tracing bus and accepts a processor
+                (OpenAI Agents SDK)
+  noop          nothing to do
+
+The one thing that does not generalise is *ordering*, and that is why this is a
+two-phase interface rather than a single ``install()`` call:
+
+  phase 1  requirements()  runs BEFORE the TracerProvider is built, and before
+                           the framework is touched. Frameworks that read
+                           configuration from the environment at import time
+                           can only be influenced here.
+  phase 2  attach()        runs AFTER the provider exists, for anything that
+                           needs to be handed a provider.
+
+This is not theoretical. Strands' Tracer reads OTEL_SEMCONV_STABILITY_OPT_IN in
+its constructor and caches the result for the process lifetime, while
+OpenInference's instrumentor must be given a live provider. A single-phase
+interface cannot satisfy both.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from logging import Logger
+from typing import Any, Protocol
+
+from opentelemetry.sdk.trace import TracerProvider
+
+from ..config import Settings
+
+
+@dataclass(frozen=True)
+class Requirements:
+    """What an adapter needs in place before the provider is built."""
+
+    # Applied only if the variable is currently unset. Never clobber an operator.
+    env: dict[str, str] = field(default_factory=dict)
+    resource_attributes: dict[str, str] = field(default_factory=dict)
+    warnings: tuple[str, ...] = ()
+
+
+@dataclass
+class AttachContext:
+    tracer_provider: TracerProvider
+    settings: Settings
+    logger: Logger
+
+
+@dataclass(frozen=True)
+class AttachResult:
+    ok: bool
+    mechanism: str  # native | instrumentor | processor | noop
+    detail: str = ""
+    emitted_span_kinds: frozenset[str] = frozenset()
+
+
+class Adapter(Protocol):
+    """Implement this in your own package and publish it as an entry point.
+
+    Adding a framework must not require touching anything outside
+    ``adapters/``, a mapping pack, and a conformance fixture.
+    """
+
+    name: str
+    semconv_family: str
+    mapping_pack: str
+
+    def detect(self) -> bool:
+        """Is this framework installed and plausibly in use?"""
+
+    def requirements(self) -> Requirements: ...
+
+    def attach(self, ctx: AttachContext) -> AttachResult: ...
+
+    def detach(self) -> None:
+        """Undo attach(). Must be idempotent; used by tests and re-init."""
+
+    def handles(self) -> list[Any]:
+        """Objects the application must wire in by hand, if any.
+
+        Empty for auto-instrumenting frameworks. Non-empty for frameworks where
+        some call sites take explicit callbacks (LangGraph), so that
+        ``tracing.handles()`` can hand them over without the application
+        importing an instrumentor directly.
+        """
+
+
+class BaseAdapter:
+    """Optional convenience base so a minimal adapter is a few lines."""
+
+    name: str = "unnamed"
+    semconv_family: str = "unknown"
+    mapping_pack: str = "unknown@1"
+
+    def detect(self) -> bool:
+        return False
+
+    def requirements(self) -> Requirements:
+        return Requirements()
+
+    def attach(self, ctx: AttachContext) -> AttachResult:
+        return AttachResult(ok=True, mechanism="noop")
+
+    def detach(self) -> None:
+        return None
+
+    def handles(self) -> list[Any]:
+        return []
+
+
+_REQUIRED_ATTRS = ("name", "semconv_family", "mapping_pack")
+_REQUIRED_METHODS = ("detect", "requirements", "attach", "detach", "handles")
+
+
+def validate_adapter(candidate: Any) -> None:
+    """Structural check with a useful error message.
+
+    ``runtime_checkable`` Protocols cannot verify non-method members, and a
+    third-party adapter missing ``mapping_pack`` would otherwise fail much later
+    at ingest, as unmapped spans.
+    """
+    missing = [a for a in _REQUIRED_ATTRS if not isinstance(getattr(candidate, a, None), str)]
+    if missing:
+        raise TypeError(f"{candidate!r} is missing string attributes: {missing}")
+    not_callable = [m for m in _REQUIRED_METHODS if not callable(getattr(candidate, m, None))]
+    if not_callable:
+        raise TypeError(f"{candidate!r} is missing methods: {not_callable}")

sonar_tracing-0.1.0/src/sonar_tracing/adapters/registry.py

@@ -0,0 +1,75 @@
+"""Adapter discovery.
+
+Framework support is a plugin, not a branch. There is no ``if framework ==
+"strands"`` here or anywhere else in core: adapters are resolved from the
+``sonar_tracing.adapters`` entry point group, so a new framework ships as a new
+package.
+
+The builtin table is a fallback for running from a source checkout where package
+metadata may not be installed. It maps name -> import target, never name ->
+behaviour, and is empty by default: every adapter ships as its own package and
+registers an entry point.
+"""
+
+from __future__ import annotations
+
+import importlib
+from importlib.metadata import entry_points
+
+from ..safety import rate_limited, safe
+from .base import Adapter, validate_adapter
+
+ENTRY_POINT_GROUP = "sonar_tracing.adapters"
+
+_BUILTIN: dict[str, str] = {}
+
+
+def available() -> dict[str, str]:
+    """name -> "module:attr" for every discoverable adapter."""
+    found = dict(_BUILTIN)
+    try:
+        for entry_point in entry_points(group=ENTRY_POINT_GROUP):
+            found[entry_point.name] = entry_point.value
+    except Exception as exc:  # noqa: BLE001 - discovery must not break init
+        rate_limited.error("registry.discover", f"entry point discovery failed: {exc!r}", exc)
+    return found
+
+
+@safe("registry.load", default=None)
+def load(name: str) -> Adapter | None:
+    target = available().get(name)
+    if target is None:
+        rate_limited.warn_once(
+            f"registry.unknown.{name}",
+            f"unknown framework {name!r}; known adapters: {sorted(available())}",
+        )
+        return None
+
+    module_name, _, attr = target.partition(":")
+    adapter = getattr(importlib.import_module(module_name), attr)()
+    validate_adapter(adapter)
+    return adapter
+
+
+def resolve(frameworks: tuple[str, ...]) -> list[Adapter]:
+    """Turn the ``framework=`` argument into concrete adapters.
+
+    ``("auto",)`` loads every discoverable adapter and keeps the ones whose
+    ``detect()`` says the framework is present.
+    """
+    if frameworks == ("auto",) or "auto" in frameworks:
+        resolved: list[Adapter] = []
+        for name in sorted(available()):
+            adapter = load(name)
+            if adapter is None:
+                continue
+            try:
+                if adapter.detect():
+                    resolved.append(adapter)
+            except Exception as exc:  # noqa: BLE001
+                rate_limited.error(
+                    f"registry.detect.{name}", f"adapter {name!r} detect() failed: {exc!r}", exc
+                )
+        return resolved
+
+    return [a for a in (load(name) for name in frameworks) if a is not None]