sonar-tracing-strands 0.1.0__tar.gz

sonar_tracing_strands-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_strands-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_strands-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.5
+Name: sonar-tracing-strands
+Version: 0.1.0
+Summary: AWS Strands Agents 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,opentelemetry,sonar,strands,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: sonar-tracing>=0.1
+Requires-Dist: strands-agents>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sonar-tracing-strands
+
+AWS Strands Agents adapter for [`sonar-tracing`](https://pypi.org/project/sonar-tracing/).
+
+Installing this package makes the `strands` 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-strands
+```
+
+```python
+import sonar_tracing as tracing
+
+tracing.init(service_name="support-agent", framework="strands")
+```
+
+Strands is OpenTelemetry-native, so this adapter installs no instrumentation. Its
+job is to pin the semantic-convention vocabulary Strands reads at import time and
+stamp the active convention onto the OTel Resource so the ingest side never has
+to guess.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sonar_tracing_strands-0.1.0/README.md

@@ -0,0 +1,27 @@
+# sonar-tracing-strands
+
+AWS Strands Agents adapter for [`sonar-tracing`](https://pypi.org/project/sonar-tracing/).
+
+Installing this package makes the `strands` 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-strands
+```
+
+```python
+import sonar_tracing as tracing
+
+tracing.init(service_name="support-agent", framework="strands")
+```
+
+Strands is OpenTelemetry-native, so this adapter installs no instrumentation. Its
+job is to pin the semantic-convention vocabulary Strands reads at import time and
+stamp the active convention onto the OTel Resource so the ingest side never has
+to guess.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sonar_tracing_strands-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "sonar-tracing-strands"
+version = "0.1.0"
+description = "AWS Strands Agents 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", "strands", "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",
+    "strands-agents>=1.0",
+]
+
+[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"]
+strands = "sonar_tracing_strands:StrandsAdapter"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sonar_tracing_strands"]

sonar_tracing_strands-0.1.0/src/sonar_tracing_strands/__init__.py

@@ -0,0 +1,115 @@
+"""AWS Strands Agents adapter for sonar-tracing.
+
+Strands is OpenTelemetry-native. ``strands.telemetry.tracer.Tracer`` calls
+``trace_api.get_tracer_provider()`` itself and instruments LLM calls, tool calls,
+retrievers and event-loop cycles against whatever provider it finds. It only
+bootstraps its own provider if the application explicitly constructs
+``StrandsTelemetry``.
+
+So the correct integration is: own the global provider, then get out of the way.
+``attach()`` here installs nothing. That is the expected outcome for a native
+framework, not a gap - and it is useful evidence that the adapter interface is
+not over-fitted to instrumentor-shaped frameworks.
+
+The real work is in ``requirements()``, phase 1. Strands' Tracer reads
+OTEL_SEMCONV_STABILITY_OPT_IN in its constructor and caches the result for the
+process lifetime, choosing between two incompatible attribute vocabularies:
+
+    default                     gen_ai.usage.prompt_tokens / completion_tokens
+    gen_ai_latest_experimental  gen_ai.usage.input_tokens  / output_tokens
+
+We pin the newer one so the data is consistent across services, and stamp which
+convention is active on the Resource so ingest never has to guess. The mapping
+pack handles both vocabularies regardless, via ordered fallbacks - pinning is
+about consistency, not about the mapper's capability.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+
+from sonar_tracing.adapters.base import AttachContext, AttachResult, Requirements
+from sonar_tracing.semconv import FAMILY_GEN_AI, SONAR_FRAMEWORK_VERSION
+
+__all__ = ["StrandsAdapter"]
+
+SEMCONV_OPT_IN_VAR = "OTEL_SEMCONV_STABILITY_OPT_IN"
+DEFAULT_OPT_IN = "gen_ai_latest_experimental"
+
+# Override with SONAR_STRANDS_SEMCONV_OPT_IN="" to leave Strands on its default.
+OPT_IN_OVERRIDE_VAR = "SONAR_STRANDS_SEMCONV_OPT_IN"
+
+
+class StrandsAdapter:
+    name = "strands"
+    semconv_family = FAMILY_GEN_AI
+    mapping_pack = "strands@1"
+
+    def detect(self) -> bool:
+        return importlib.util.find_spec("strands") is not None
+
+    def requirements(self) -> Requirements:
+        env: dict[str, str] = {}
+        warnings: list[str] = []
+        resource: dict[str, str] = {}
+
+        version = _strands_version()
+        if version:
+            resource[SONAR_FRAMEWORK_VERSION] = version
+
+        desired = os.environ.get(OPT_IN_OVERRIDE_VAR, DEFAULT_OPT_IN)
+        existing = os.environ.get(SEMCONV_OPT_IN_VAR)
+        if existing:
+            warnings.append(
+                f"{SEMCONV_OPT_IN_VAR}={existing!r} is already set; leaving it alone. "
+                "The strands@1 mapping pack normalises either vocabulary."
+            )
+            resource["sonar.strands.semconv_opt_in"] = existing
+        elif desired:
+            env[SEMCONV_OPT_IN_VAR] = desired
+            resource["sonar.strands.semconv_opt_in"] = desired
+
+        if _tracer_singleton_exists():
+            warnings.append(
+                "strands.telemetry.tracer was already constructed before tracing.init(). "
+                "Spans will still be captured (OTel's proxy provider resolves late), but "
+                "environment-derived Strands settings were already read and cannot be "
+                "changed. Call tracing.init() before creating any Agent."
+            )
+
+        return Requirements(env=env, resource_attributes=resource, warnings=tuple(warnings))
+
+    def attach(self, ctx: AttachContext) -> AttachResult:
+        version = _strands_version() or "unknown"
+        return AttachResult(
+            ok=True,
+            mechanism="native",
+            detail=(
+                f"strands {version}: no instrumentation installed; the framework "
+                f"resolves the global TracerProvider itself"
+            ),
+            emitted_span_kinds=frozenset({"agent", "llm", "tool", "retrieval"}),
+        )
+
+    def detach(self) -> None:
+        return None
+
+    def handles(self) -> list[object]:
+        return []
+
+
+def _strands_version() -> str | None:
+    try:
+        from importlib.metadata import version
+
+        return version("strands-agents")
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _tracer_singleton_exists() -> bool:
+    """True if Strands already built its Tracer, meaning env config is frozen."""
+    module = sys.modules.get("strands.telemetry.tracer")
+    return module is not None and getattr(module, "_tracer_instance", None) is not None

sonar_tracing_strands-0.1.0/tests/test_strands_adapter.py

@@ -0,0 +1,42 @@
+"""The Strands adapter, as its own package."""
+
+from __future__ import annotations
+
+import pytest
+from sonar_tracing.testing import assert_adapter_contract
+from sonar_tracing_strands import StrandsAdapter
+
+
+def test_strands_adapter_satisfies_the_contract() -> None:
+    assert_adapter_contract(StrandsAdapter())
+
+
+def test_strands_installs_no_instrumentation() -> None:
+    """A native framework needs the provider to exist and nothing else.
+
+    An adapter that does nothing is a valid adapter. If this ever starts
+    wrapping or re-instrumenting Strands, something has gone wrong.
+    """
+    adapter = StrandsAdapter()
+    result = adapter.attach(ctx=None)  # type: ignore[arg-type]  # unused by this adapter
+    assert result.ok
+    assert result.mechanism == "native"
+
+
+def test_strands_pins_the_semconv_vocabulary_before_the_provider_is_built(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Phase 1 exists because Strands reads this env var in its constructor
+    and caches the result for the process lifetime."""
+    monkeypatch.delenv("OTEL_SEMCONV_STABILITY_OPT_IN", raising=False)
+    requirements = StrandsAdapter().requirements()
+    assert requirements.env["OTEL_SEMCONV_STABILITY_OPT_IN"] == "gen_ai_latest_experimental"
+
+
+def test_an_operator_set_semconv_var_is_never_clobbered(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("OTEL_SEMCONV_STABILITY_OPT_IN", "gen_ai_span_attributes_only")
+    requirements = StrandsAdapter().requirements()
+    assert "OTEL_SEMCONV_STABILITY_OPT_IN" not in requirements.env
+    assert any("already set" in w for w in requirements.warnings)