anytrace 0.9.0__py3-none-any.whl

anytrace/__init__.py

@@ -0,0 +1,50 @@
+"""anytrace — vendor-neutral agent tracing over OpenTelemetry.
+
+Public API surface is only what is exported here. Keep it small.
+"""
+
+from anytrace.context import extract_context, inject_context, use_context
+from anytrace.core import (
+    add_event,
+    add_metadata,
+    add_tags,
+    init,
+    instrument_logging,
+    record_generation,
+    set_io,
+    set_session,
+    set_user,
+    shutdown,
+    stats,
+    trace_agent,
+    trace_chain,
+    trace_embedding,
+    trace_retriever,
+    trace_span,
+    trace_tool,
+    traced,
+)
+
+__all__ = [
+    "add_event",
+    "add_metadata",
+    "add_tags",
+    "extract_context",
+    "init",
+    "inject_context",
+    "instrument_logging",
+    "record_generation",
+    "set_io",
+    "set_session",
+    "set_user",
+    "shutdown",
+    "stats",
+    "trace_agent",
+    "trace_chain",
+    "trace_embedding",
+    "trace_retriever",
+    "trace_span",
+    "trace_tool",
+    "traced",
+    "use_context",
+]

anytrace/adapters/__init__.py

@@ -0,0 +1,33 @@
+"""Backend adapters: per-backend OTLP endpoint, auth headers, and attribute mapping."""
+
+from anytrace.adapters.base import BackendAdapter
+from anytrace.config import ConfigError
+
+__all__ = ["BackendAdapter", "get_adapter", "register_adapter"]
+
+_REGISTRY: dict[str, BackendAdapter] = {}
+
+
+def register_adapter(adapter: BackendAdapter) -> None:
+    _REGISTRY[adapter.name] = adapter
+
+
+def get_adapter(kind: str) -> BackendAdapter:
+    try:
+        return _REGISTRY[kind]
+    except KeyError:
+        raise ConfigError(
+            f"no adapter registered for backend kind {kind!r}; "
+            f"registered kinds: {sorted(_REGISTRY) or 'none'}"
+        ) from None
+
+
+from anytrace.adapters.langfuse import LangfuseAdapter  # noqa: E402
+from anytrace.adapters.langsmith import LangSmithAdapter  # noqa: E402
+from anytrace.adapters.otlp import OTLPAdapter  # noqa: E402
+from anytrace.adapters.phoenix import PhoenixAdapter  # noqa: E402
+
+register_adapter(LangfuseAdapter())
+register_adapter(LangSmithAdapter())
+register_adapter(PhoenixAdapter())
+register_adapter(OTLPAdapter())

anytrace/adapters/base.py

@@ -0,0 +1,36 @@
+"""Adapter interface every backend must implement."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Protocol, runtime_checkable
+
+from anytrace.config import BackendConfig as Config
+
+Attributes = Mapping[str, Any]
+
+
+@runtime_checkable
+class BackendAdapter(Protocol):
+    """A tracing backend reachable via OTLP.
+
+    Adapters carry no vendor SDK dependencies: they only supply the OTLP
+    endpoint, auth headers, and a GenAI -> backend attribute mapping.
+    """
+
+    @property
+    def name(self) -> str:
+        """Stable identifier used in configuration (e.g. "langsmith", "langfuse")."""
+        ...
+
+    def endpoint(self, cfg: Config) -> str:
+        """OTLP HTTP endpoint URL for this backend."""
+        ...
+
+    def headers(self, cfg: Config) -> dict[str, str]:
+        """Auth and transport headers for the OTLP exporter."""
+        ...
+
+    def map_attributes(self, attrs: Attributes) -> dict[str, Any]:
+        """Translate GenAI semantic-convention attributes to backend-specific ones."""
+        ...

anytrace/adapters/langfuse.py

@@ -0,0 +1,80 @@
+"""Langfuse adapter: OTLP endpoint, Basic auth, and attribute mapping.
+
+Verified against https://langfuse.com/docs/opentelemetry/get-started (2026-07):
+OTLP traces endpoint is ``{LANGFUSE_ENDPOINT}/api/public/otel/v1/traces``, auth is
+HTTP Basic with ``public_key:secret_key``.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from anytrace.adapters.base import Attributes
+from anytrace.config import BackendConfig
+
+_OTLP_PATH = "/api/public/otel/v1/traces"
+
+# The FULL GenAI -> Langfuse mapping lives in this one table.
+# Langfuse understands gen_ai.* natively, so originals are kept as-is;
+# these entries ADD the Langfuse-native name alongside the original.
+_ATTRIBUTE_MAP: dict[str, str] = {
+    "user.id": "langfuse.user.id",
+    "session.id": "langfuse.session.id",
+    "anytrace.release": "langfuse.release",
+    "anytrace.version": "langfuse.version",
+}
+
+# gen_ai.operation.name -> langfuse.observation.type. Falls back to the model
+# marker. Langfuse supports tool/retriever/embedding/agent/... types since v3.
+_OPERATION_TYPES: dict[str, str] = {
+    "chat": "generation",
+    "completion": "generation",
+    "execute_tool": "tool",
+    "retrieval": "retriever",
+    "embeddings": "embedding",
+    "invoke_agent": "agent",
+    "chain": "chain",
+}
+
+# Spans carrying this attribute are LLM calls and get typed as generations.
+_GENERATION_MARKER = "gen_ai.request.model"
+
+# Custom attributes (add_metadata / trace_span kwargs) only become first-class
+# Langfuse metadata when prefixed; mirror anything outside these namespaces
+# into langfuse.observation.metadata.<key> (audit 2026-07-15).
+_PASSTHROUGH_PREFIXES = ("gen_ai.", "langfuse.", "llm.", "http.", "url.", "anytrace.")
+
+
+class LangfuseAdapter:
+    name = "langfuse"
+
+    def endpoint(self, cfg: BackendConfig) -> str:
+        base = cfg.endpoint.rstrip("/")
+        if base.endswith(_OTLP_PATH):
+            return base
+        return base + _OTLP_PATH
+
+    def headers(self, cfg: BackendConfig) -> dict[str, str]:
+        credentials = f"{cfg.auth['public_key']}:{cfg.auth['secret_key']}"
+        encoded = base64.b64encode(credentials.encode()).decode()
+        return {"Authorization": f"Basic {encoded}"}
+
+    def map_attributes(self, attrs: Attributes) -> dict[str, Any]:
+        mapped = dict(attrs)
+        for source, target in _ATTRIBUTE_MAP.items():
+            if source in mapped:
+                mapped[target] = mapped[source]
+        for key, value in attrs.items():
+            if key in _ATTRIBUTE_MAP or key.startswith(_PASSTHROUGH_PREFIXES):
+                continue
+            mapped[f"langfuse.observation.metadata.{key}"] = value
+        tags = mapped.get("anytrace.tags")
+        if tags:
+            mapped["langfuse.trace.tags"] = list(tags)
+        operation = mapped.get("gen_ai.operation.name")
+        if operation in _OPERATION_TYPES:
+            mapped["langfuse.observation.type"] = _OPERATION_TYPES[operation]
+        elif _GENERATION_MARKER in mapped:
+            mapped["langfuse.observation.type"] = "generation"
+        return mapped

anytrace/adapters/langsmith.py

@@ -0,0 +1,88 @@
+"""LangSmith adapter: OTLP endpoint, x-api-key auth, and attribute mapping.
+
+Verified against https://docs.langchain.com/langsmith/trace-with-opentelemetry (2026-07):
+cloud OTLP endpoint is ``{base}/otel/v1/traces``; self-hosted appends ``/api/v1/otel``
+to the base URL (so the full traces path is ``{base}/api/v1/otel/v1/traces``).
+LangSmith natively understands ``gen_ai.*`` including ``gen_ai.usage.input_tokens`` /
+``output_tokens``, so no OpenLLMetry renaming is needed — originals are preserved.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from anytrace.adapters.base import Attributes
+from anytrace.config import BackendConfig
+
+_CLOUD_HOSTS = ("api.smith.langchain.com",)
+_TRACES_SUFFIX = "/v1/traces"
+
+# The FULL GenAI -> LangSmith mapping lives in this one table.
+# gen_ai.* passes through untouched; these entries ADD LangSmith-native names.
+_ATTRIBUTE_MAP: dict[str, str] = {
+    "user.id": "langsmith.metadata.user_id",
+    "session.id": "langsmith.metadata.session_id",
+    # LangSmith has no cost attribute (it computes its own from model pricing);
+    # mirror the reported value into metadata so it isn't lost (audit 2026-07-15).
+    "gen_ai.usage.cost": "langsmith.metadata.cost",
+    "anytrace.release": "langsmith.metadata.release",
+    "anytrace.version": "langsmith.metadata.version",
+}
+
+# gen_ai.operation.name -> langsmith.span.kind. Falls back to the model marker.
+_OPERATION_KINDS: dict[str, str] = {
+    "chat": "llm",
+    "completion": "llm",
+    "execute_tool": "tool",
+    "retrieval": "retriever",
+    "embeddings": "embedding",
+    "invoke_agent": "chain",  # LangSmith has no agent run type
+    "chain": "chain",
+}
+
+# Spans carrying this attribute are LLM calls and get langsmith.span.kind = "llm".
+_LLM_MARKER = "gen_ai.request.model"
+
+# Custom attributes (add_metadata / trace_span kwargs) are invisible to LangSmith
+# unless prefixed; anything outside these namespaces gets mirrored into
+# langsmith.metadata.<key> (audit 2026-07-15: status/eta_days/order_id were dropped).
+_PASSTHROUGH_PREFIXES = ("gen_ai.", "langsmith.", "llm.", "http.", "url.", "anytrace.")
+
+
+class LangSmithAdapter:
+    name = "langsmith"
+
+    def endpoint(self, cfg: BackendConfig) -> str:
+        base = cfg.endpoint.rstrip("/")
+        if "/otel" in base:
+            # Caller already supplied the OTLP base; just ensure the traces path.
+            return base if base.endswith(_TRACES_SUFFIX) else base + _TRACES_SUFFIX
+        if any(host in base for host in _CLOUD_HOSTS):
+            return base + "/otel" + _TRACES_SUFFIX
+        return base + "/api/v1/otel" + _TRACES_SUFFIX
+
+    def headers(self, cfg: BackendConfig) -> dict[str, str]:
+        headers = {"x-api-key": cfg.auth["api_key"]}
+        project = cfg.options.get("project")
+        if project:
+            headers["Langsmith-Project"] = project
+        return headers
+
+    def map_attributes(self, attrs: Attributes) -> dict[str, Any]:
+        mapped = dict(attrs)
+        for source, target in _ATTRIBUTE_MAP.items():
+            if source in mapped:
+                mapped[target] = mapped[source]
+        for key, value in attrs.items():
+            if key in _ATTRIBUTE_MAP or key.startswith(_PASSTHROUGH_PREFIXES):
+                continue
+            mapped[f"langsmith.metadata.{key}"] = value
+        tags = mapped.get("anytrace.tags")
+        if tags:
+            mapped["langsmith.span.tags"] = ",".join(str(t) for t in tags)
+        operation = mapped.get("gen_ai.operation.name")
+        if operation in _OPERATION_KINDS:
+            mapped["langsmith.span.kind"] = _OPERATION_KINDS[operation]
+        elif _LLM_MARKER in mapped:
+            mapped["langsmith.span.kind"] = "llm"
+        return mapped

anytrace/adapters/otlp.py

@@ -0,0 +1,36 @@
+"""Generic OTLP adapter: any collector or OTLP-native receiver, no dialect.
+
+Attributes pass through unchanged (neutral ``gen_ai.*`` / ``anytrace.*``) —
+when routing through an OTel Collector to a vendor, do vendor mapping in the
+collector, or configure that vendor's anytrace adapter directly instead.
+Optional headers (e.g. collector auth) come from ``OTLP_HEADERS="k=v,k2=v2"``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from anytrace.adapters.base import Attributes
+from anytrace.config import BackendConfig
+
+_OTLP_PATH = "/v1/traces"
+
+
+class OTLPAdapter:
+    name = "otlp"
+
+    def endpoint(self, cfg: BackendConfig) -> str:
+        base = cfg.endpoint.rstrip("/")
+        return base if base.endswith(_OTLP_PATH) else base + _OTLP_PATH
+
+    def headers(self, cfg: BackendConfig) -> dict[str, str]:
+        raw = cfg.options.get("headers", "")
+        headers: dict[str, str] = {}
+        for pair in raw.split(","):
+            if "=" in pair:
+                key, _, value = pair.partition("=")
+                headers[key.strip()] = value.strip()
+        return headers
+
+    def map_attributes(self, attrs: Attributes) -> dict[str, Any]:
+        return dict(attrs)

anytrace/adapters/phoenix.py

@@ -0,0 +1,71 @@
+"""Arize Phoenix adapter: OTLP endpoint and OpenInference attribute mapping.
+
+Phoenix (OSS) ingests OTLP at ``{PHOENIX_ENDPOINT}/v1/traces`` — no auth for
+self-hosted; Phoenix Cloud uses an ``api_key`` header (PHOENIX_API_KEY).
+Phoenix's native dialect is OpenInference, so the mapping mirrors GenAI
+attributes into OpenInference names; originals are preserved.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from anytrace.adapters.base import Attributes
+from anytrace.config import BackendConfig
+
+_OTLP_PATH = "/v1/traces"
+
+# The FULL GenAI -> OpenInference mapping lives in these two tables.
+_ATTRIBUTE_MAP: dict[str, str] = {
+    "gen_ai.request.model": "llm.model_name",
+    "gen_ai.usage.input_tokens": "llm.token_count.prompt",
+    "gen_ai.usage.output_tokens": "llm.token_count.completion",
+    "gen_ai.prompt": "input.value",
+    "gen_ai.completion": "output.value",
+    # user.id / session.id are OpenInference-native already — passed through.
+}
+
+# gen_ai.operation.name -> openinference.span.kind (values are UPPERCASE).
+_OPERATION_KINDS: dict[str, str] = {
+    "chat": "LLM",
+    "completion": "LLM",
+    "execute_tool": "TOOL",
+    "retrieval": "RETRIEVER",
+    "embeddings": "EMBEDDING",
+    "invoke_agent": "AGENT",
+    "chain": "CHAIN",
+}
+
+_LLM_MARKER = "gen_ai.request.model"
+
+
+class PhoenixAdapter:
+    name = "phoenix"
+
+    def endpoint(self, cfg: BackendConfig) -> str:
+        base = cfg.endpoint.rstrip("/")
+        return base if base.endswith(_OTLP_PATH) else base + _OTLP_PATH
+
+    def headers(self, cfg: BackendConfig) -> dict[str, str]:
+        api_key = cfg.auth.get("api_key")
+        if not api_key:
+            return {}
+        # Phoenix Cloud (app.phoenix.arize.com) authenticates via Bearer
+        # (live-verified 2026-07-16: api_key header alone gets 401); the
+        # legacy api_key header is included for older self-hosted deployments.
+        return {"Authorization": f"Bearer {api_key}", "api_key": api_key}
+
+    def map_attributes(self, attrs: Attributes) -> dict[str, Any]:
+        mapped = dict(attrs)
+        for source, target in _ATTRIBUTE_MAP.items():
+            if source in mapped:
+                mapped[target] = mapped[source]
+        tags = mapped.get("anytrace.tags")
+        if tags:
+            mapped["tag.tags"] = list(tags)
+        operation = mapped.get("gen_ai.operation.name")
+        if operation in _OPERATION_KINDS:
+            mapped["openinference.span.kind"] = _OPERATION_KINDS[operation]
+        elif _LLM_MARKER in mapped:
+            mapped["openinference.span.kind"] = "LLM"
+        return mapped

anytrace/adapters/processor.py

@@ -0,0 +1,48 @@
+"""Exporter wrapper that applies an adapter's attribute mapping just before export.
+
+One recorded span fans out to N backends; each backend's exporter sees the span
+rewritten in its own attribute dialect, while the original span is untouched.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+
+from anytrace.adapters.base import BackendAdapter
+
+
+class MappingSpanExporter(SpanExporter):
+    """Delegates to ``wrapped`` after rewriting attributes via ``adapter.map_attributes``."""
+
+    def __init__(self, adapter: BackendAdapter, wrapped: SpanExporter) -> None:
+        self._adapter = adapter
+        self._wrapped = wrapped
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        return self._wrapped.export([self._map(span) for span in spans])
+
+    def _map(self, span: ReadableSpan) -> ReadableSpan:
+        mapped = self._adapter.map_attributes(dict(span.attributes or {}))
+        return ReadableSpan(
+            name=span.name,
+            context=span.get_span_context(),
+            parent=span.parent,
+            resource=span.resource,
+            attributes=mapped,
+            events=span.events,
+            links=span.links,
+            kind=span.kind,
+            status=span.status,
+            start_time=span.start_time,
+            end_time=span.end_time,
+            instrumentation_scope=span.instrumentation_scope,
+        )
+
+    def shutdown(self) -> None:
+        self._wrapped.shutdown()
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return self._wrapped.force_flush(timeout_millis)

anytrace/config/__init__.py

@@ -0,0 +1,10 @@
+"""Configuration loading: env vars first, optional YAML override, with validation."""
+
+from anytrace.config.loader import (
+    BackendConfig,
+    ConfigError,
+    TracingConfig,
+    load_config,
+)
+
+__all__ = ["BackendConfig", "ConfigError", "TracingConfig", "load_config"]