trodo-python 2.3.0__tar.gz → 2.4.0__tar.gz

{trodo_python-2.3.0/trodo_python.egg-info → trodo_python-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.3.0
+Version: 2.4.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -19,6 +19,10 @@ Description-Content-Type: text/markdown
 Requires-Dist: requests>=2.28.0
 Provides-Extra: async
 Requires-Dist: httpx>=0.27.0; extra == "async"
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "otlp"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otlp"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == "otlp"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -37,6 +41,39 @@ pip install trodo-python
 
 Requires Python 3.8+.
 
+## OpenTelemetry / OTLP path (NEW in 2.4.0)
+
+Already running OTel? Skip the Trodo SDK install entirely and point your existing pipeline at Trodo. Two env vars:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://sdkapi.trodo.ai
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${TRODO_SITE_ID}"
+```
+
+The Bearer token is your **site_id** — same value you'd pass to `trodo.init(site_id=...)`. Get it from the [Integration Manager](https://app.trodo.ai/dashboard/integrations).
+
+Use this when **you already run OTel** (Datadog, Jaeger, Honeycomb) and want Trodo as an additional destination. Install `trodo-python` and call `trodo.register_otel(site_id=..., mode='otlp')` to attach our OTLP exporter without replacing your existing setup. `wrap_agent` then routes through OTel so auto-instrumented children share the same trace.
+
+```python
+# At app startup (after your existing OTel provider is registered)
+import os, trodo
+
+trodo.register_otel(
+    site_id=os.environ['TRODO_SITE_ID'],
+    mode='otlp',
+)
+```
+
+`mode='otlp'` requires the optional `[otlp]` extras:
+
+```bash
+pip install 'trodo-python[otlp]'
+```
+
+The SDK raises a friendly install hint if you call `mode='otlp'` without them.
+
+For richer Trodo features on top (`wrap_agent`, `feedback`, `track_mcp`), continue with the SDK quick start below.
+
 ## Quick Start
 
 ```python

trodo_python-2.3.0/PKG-INFO → trodo_python-2.4.0/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.4
-Name: trodo-python
-Version: 2.3.0
-Summary: Trodo Analytics SDK for Python — server-side event tracking
-License: ISC
-Keywords: analytics,tracking,trodo,server-side
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: ISC License (ISCL)
-Classifier: Operating System :: OS Independent
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.28.0
-Provides-Extra: async
-Requires-Dist: httpx>=0.27.0; extra == "async"
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: responses>=0.25.0; extra == "dev"
-Requires-Dist: httpx>=0.27.0; extra == "dev"
-
 # trodo-python
 
 Server-side Python SDK for [Trodo Analytics](https://trodo.ai). Track backend events, identify users, manage people/groups, and instrument AI agents — all unified with your frontend data under the same `site_id`.
@@ -37,6 +10,39 @@ pip install trodo-python
 
 Requires Python 3.8+.
 
+## OpenTelemetry / OTLP path (NEW in 2.4.0)
+
+Already running OTel? Skip the Trodo SDK install entirely and point your existing pipeline at Trodo. Two env vars:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://sdkapi.trodo.ai
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${TRODO_SITE_ID}"
+```
+
+The Bearer token is your **site_id** — same value you'd pass to `trodo.init(site_id=...)`. Get it from the [Integration Manager](https://app.trodo.ai/dashboard/integrations).
+
+Use this when **you already run OTel** (Datadog, Jaeger, Honeycomb) and want Trodo as an additional destination. Install `trodo-python` and call `trodo.register_otel(site_id=..., mode='otlp')` to attach our OTLP exporter without replacing your existing setup. `wrap_agent` then routes through OTel so auto-instrumented children share the same trace.
+
+```python
+# At app startup (after your existing OTel provider is registered)
+import os, trodo
+
+trodo.register_otel(
+    site_id=os.environ['TRODO_SITE_ID'],
+    mode='otlp',
+)
+```
+
+`mode='otlp'` requires the optional `[otlp]` extras:
+
+```bash
+pip install 'trodo-python[otlp]'
+```
+
+The SDK raises a friendly install hint if you call `mode='otlp'` without them.
+
+For richer Trodo features on top (`wrap_agent`, `feedback`, `track_mcp`), continue with the SDK quick start below.
+
 ## Quick Start
 
 ```python

{trodo_python-2.3.0 → trodo_python-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trodo-python"
-version = "2.3.0"
+version = "2.4.0"
 description = "Trodo Analytics SDK for Python — server-side event tracking"
 readme = "README.md"
 license = { text = "ISC" }
@@ -28,6 +28,13 @@ classifiers = [
 
 [project.optional-dependencies]
 async = ["httpx>=0.27.0"]
+# OTLP-mode dependencies for register_otel(mode='otlp'). Install with:
+#   pip install 'trodo-python[otlp]'
+otlp = [
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.20.0",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov",

trodo_python-2.4.0/tests/test_register_otel.py

@@ -0,0 +1,183 @@
+"""Tests for register_otel + transport dispatch (Python parity with the TS SDK)."""
+from __future__ import annotations
+
+import pytest
+
+from trodo.otel.register import register_otel, _reset_for_tests
+from trodo.otel.transport import (
+    get_transport_mode,
+    get_otel_tracer,
+    set_otel_transport,
+    _reset_transport_for_tests,
+)
+from trodo.otel.processor import TrodoSpanProcessor
+from trodo.otel.wrap_agent import wrap_agent
+
+
+@pytest.fixture(autouse=True)
+def reset_state():
+    _reset_for_tests()
+    yield
+    _reset_for_tests()
+
+
+# ---------------------------------------------------------------------------
+# register_otel — argument validation + idempotency
+# ---------------------------------------------------------------------------
+
+
+def test_raises_when_site_id_missing(processor):
+    with pytest.raises(ValueError, match="site_id"):
+        register_otel(site_id="", processor=processor)
+
+
+def test_raises_when_processor_missing():
+    with pytest.raises(ValueError, match="processor"):
+        register_otel(site_id="site_x", processor=None)  # type: ignore[arg-type]
+
+
+def test_idempotency_warns_on_second_call(processor):
+    first = register_otel(site_id="site_x", processor=processor, mode="trodo")
+    assert first.mode == "trodo"
+    assert first.fresh is True
+
+    with pytest.warns(UserWarning, match="already called"):
+        second = register_otel(site_id="site_x", processor=processor, mode="trodo")
+    assert second is first
+
+
+def test_unknown_mode_raises(processor):
+    with pytest.raises(ValueError, match="unknown mode"):
+        register_otel(site_id="site_x", processor=processor, mode="bogus")
+
+
+# ---------------------------------------------------------------------------
+# Mode dispatch — 'trodo' default, 'otlp' raises if peer deps missing
+# ---------------------------------------------------------------------------
+
+
+def test_trodo_mode_succeeds_without_otlp_peer_deps(processor):
+    result = register_otel(site_id="site_x", processor=processor, mode="trodo")
+    assert result.mode == "trodo"
+    # active_instrumentations is best-effort; just confirm it's a list.
+    assert isinstance(result.active_instrumentations, list)
+
+
+def test_otlp_mode_emits_install_hint_when_peer_deps_missing(processor, monkeypatch):
+    # Ensure opentelemetry imports fail to simulate a fresh install without
+    # the 'otlp' extras. We do this by replacing opentelemetry.sdk.trace's
+    # spec in sys.modules with None, mimicking ImportError at import time.
+    import sys
+
+    sentinel = "opentelemetry.exporter.otlp.proto.http.trace_exporter"
+    monkeypatch.setitem(sys.modules, sentinel, None)
+
+    with pytest.raises(RuntimeError, match=r"register_otel\(mode='otlp'\) requires"):
+        register_otel(site_id="site_x", processor=processor, mode="otlp")
+
+
+# ---------------------------------------------------------------------------
+# Transport dispatch — wrap_agent in 'otlp' mode goes through the OTel tracer
+# ---------------------------------------------------------------------------
+
+
+class RecordedSpan:
+    def __init__(self, name: str, trace_id: int, span_id: int):
+        self.name = name
+        self.trace_id = trace_id
+        self.span_id = span_id
+        self.attrs = {}
+        self.ended = False
+        self.exception = None
+        self.status = None
+
+    def set_attribute(self, key, value):
+        self.attrs[key] = value
+
+    def record_exception(self, e):
+        self.exception = e
+
+    def set_status(self, s):
+        self.status = s
+
+    def end(self):
+        self.ended = True
+
+    def get_span_context(self):
+        class C:
+            pass
+        c = C()
+        c.trace_id = self.trace_id
+        c.span_id = self.span_id
+        return c
+
+
+class MockTracer:
+    def __init__(self):
+        self.spans: list = []
+        self._next_id = 1
+
+    def start_span(self, name):
+        span = RecordedSpan(name, self._next_id, self._next_id + 1000)
+        self._next_id += 1
+        self.spans.append(span)
+        return span
+
+
+def test_wrap_agent_dispatches_to_otel_when_transport_set(processor):
+    """wrap_agent in 'otlp' transport routes through tracer.start_span and
+    sets Trodo attributes the backend OTLP controller understands."""
+    tracer = MockTracer()
+
+    class _NoopCM:
+        def __enter__(self):
+            return None
+
+        def __exit__(self, *a):
+            return None
+
+    def fake_use_span(span, end_on_exit=False):
+        return _NoopCM()
+
+    set_otel_transport(tracer, use_span=fake_use_span)
+
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="support-bot",
+        distinct_id="user-1",
+        conversation_id="conv-1",
+        metadata={"experimentId": "v3", "tier": "enterprise"},
+    ) as run:
+        run.set_input({"q": "hello"})
+        run.set_output({"a": "world"})
+
+    assert len(tracer.spans) == 1
+    span = tracer.spans[0]
+    assert span.name == "support-bot"
+    assert span.ended is True
+    assert span.attrs["trodo.agent_name"] == "support-bot"
+    assert span.attrs["trodo.distinct_id"] == "user-1"
+    assert span.attrs["trodo.conversation_id"] == "conv-1"
+    assert span.attrs["trodo.metadata.experimentId"] == "v3"
+    assert span.attrs["trodo.metadata.tier"] == "enterprise"
+    assert "ai.prompt" in span.attrs
+    assert "ai.response.text" in span.attrs
+
+
+def test_wrap_agent_legacy_path_when_no_transport(processor, http):
+    """No register_otel call → transport mode stays 'trodo' → wrap_agent
+    uses TrodoSpanProcessor + HTTP API as in 2.3.x."""
+    assert get_transport_mode() == "trodo"
+    assert get_otel_tracer() is None
+
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="legacy-agent",
+    ) as run:
+        run.set_output("done")
+
+    # Trodo HTTP API path used as in 2.3.x.
+    assert len(http.run_ingest) == 1
+    assert http.run_ingest[0]["run"]["agent_name"] == "legacy-agent"

{trodo_python-2.3.0 → trodo_python-2.4.0}/trodo/__init__.py

@@ -40,7 +40,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.3.0"
+__version__ = "2.4.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -67,6 +67,7 @@ __all__ = [
     "SpanHandle",
     "FeedbackProps",
     "init",
+    "register_otel",
     "for_user",
     "track",
     "identify",
@@ -129,6 +130,7 @@ def init(
     on_error: Optional[Any] = None,
     debug: bool = False,
     auto_instrument: bool = True,
+    otel_mode: str = "trodo",
 ) -> TrodoClient:
     """Initialise the singleton SDK instance.
 
@@ -150,10 +152,53 @@ def init(
         on_error=on_error,
         debug=debug,
         auto_instrument=auto_instrument,
+        otel_mode=otel_mode,
     )
     return _client
 
 
+def register_otel(
+    *,
+    site_id: Optional[str] = None,
+    mode: str = "trodo",
+    endpoint: Optional[str] = None,
+    service_name: str = "trodo-agent",
+) -> Any:
+    """Configure the OTel pipeline with one call.
+
+    Auto-creates the singleton TrodoClient if init() hasn't been called yet,
+    so this can replace init() for OTel-first deployments.
+
+    Modes:
+      - 'trodo' (default): bridges OTel auto-instrumentations into
+        TrodoSpanProcessor (HTTP API path). Same as init() with default config.
+      - 'otlp': registers an OTel TracerProvider with an OTLP/protobuf
+        exporter pointed at Trodo's /v1/traces. Use alongside Datadog/Jaeger
+        or for vanilla OTel-native setups.
+
+    Example:
+        import trodo
+        trodo.register_otel(site_id=os.environ['TRODO_SITE_ID'], mode='otlp')
+    """
+    global _client
+    from .otel.register import register_otel as _impl
+    if _client is None:
+        if not site_id:
+            raise ValueError(
+                "register_otel: pass site_id, or call trodo.init(site_id=...) first."
+            )
+        # Suppress legacy auto_instrument inside the constructor — register_otel
+        # below is what wires the pipeline.
+        _client = TrodoClient(site_id=site_id, auto_instrument=False)
+    return _impl(
+        site_id=site_id or _client.site_id,
+        processor=_client._get_span_processor(),
+        mode=mode,
+        endpoint=endpoint,
+        service_name=service_name,
+    )
+
+
 def for_user(
     distinct_id: str,
     session_id: Optional[str] = None,

{trodo_python-2.3.0 → trodo_python-2.4.0}/trodo/client.py

@@ -23,6 +23,7 @@ from .otel.wrap_agent import (
     current_span_id as _current_span_id,
 )
 from .otel.auto_instrument import enable_auto_instrument
+from .otel.register import register_otel as _register_otel
 from .otel.helpers import (
     tool as tool_decorator,
     track_llm_call as track_llm_call_fn,
@@ -52,11 +53,13 @@ class TrodoClient:
         on_error: Optional[Any] = None,
         debug: bool = False,
         auto_instrument: bool = True,
+        otel_mode: str = "trodo",
     ) -> None:
         if not site_id:
             raise ValueError("trodo-python: site_id is required")
 
         self.site_id = site_id
+        self._api_base = api_base
 
         self._http = HttpClient(
             api_base=api_base,
@@ -90,7 +93,22 @@ class TrodoClient:
 
         self._span_processor = TrodoSpanProcessor(http_client=self._http)
         if auto_instrument:
-            enable_auto_instrument(self._span_processor)
+            import os
+            if os.environ.get("TRODO_LEGACY_INIT") == "1":
+                # Pre-2.4 escape hatch for one minor version.
+                enable_auto_instrument(self._span_processor)
+            else:
+                _register_otel(
+                    site_id=site_id,
+                    processor=self._span_processor,
+                    mode=otel_mode,
+                    endpoint=api_base,
+                )
+
+    def _get_span_processor(self) -> TrodoSpanProcessor:
+        """Internal: expose the span processor to register_otel. Not part of
+        the public surface; subject to change between minors."""
+        return self._span_processor
 
     # --------------------------------------------------------------------------
     # Primary pattern: for_user()

trodo_python-2.4.0/trodo/otel/register.py

@@ -0,0 +1,200 @@
+"""
+register_otel — one-call setup for Trodo's tracing pipeline.
+
+Mirrors trodo-node's registerOTel. Two modes:
+
+- 'trodo' (default) — uses the existing enable_auto_instrument bridge so spans
+  from opentelemetry-instrumentation-{anthropic,openai,langchain,...} flow
+  into TrodoSpanProcessor (HTTP API path). Functionally equivalent to today's
+  init() with auto_instrument=True, exposed as a one-line OTel-native call.
+
+- 'otlp' — registers an OTel TracerProvider with an OTLP/protobuf exporter
+  pointed at Trodo's /v1/traces ingest. Use when you already have an OTel
+  pipeline (Datadog, Jaeger, Honeycomb) or want a vanilla OTel-native setup.
+  In 'otlp' mode, wrap_agent / span dispatch through the OTel tracer so
+  auto-instrumented children (Anthropic, LangChain, etc.) join the same
+  trace; backend OTLP controller groups them into one run.
+
+Idempotent — second call returns the cached configuration with a warning.
+"""
+from __future__ import annotations
+import warnings
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+from .processor import TrodoSpanProcessor
+from .auto_instrument import enable_auto_instrument
+from .transport import set_otel_transport, _reset_transport_for_tests
+
+
+@dataclass
+class RegisterOtelResult:
+    mode: str
+    active_instrumentations: List[str]
+    fresh: bool
+
+
+_registered: Optional[RegisterOtelResult] = None
+
+
+def register_otel(
+    *,
+    site_id: str,
+    processor: TrodoSpanProcessor,
+    mode: str = "trodo",
+    endpoint: Optional[str] = None,
+    service_name: str = "trodo-agent",
+    disable_instrumentations: Optional[List[str]] = None,
+) -> RegisterOtelResult:
+    """Configure Trodo's OTel pipeline. See module doc for mode semantics."""
+    global _registered
+    if _registered is not None:
+        warnings.warn(
+            "[trodo] register_otel already called; returning existing "
+            "configuration. Pass {mode} only at startup.",
+            stacklevel=2,
+        )
+        return _registered
+    if not site_id:
+        raise ValueError("register_otel: site_id is required")
+    if processor is None:
+        raise ValueError(
+            "register_otel: processor is required (typically passed "
+            "automatically via init() / TrodoClient).",
+        )
+
+    endpoint = (endpoint or "https://sdkapi.trodo.ai").rstrip("/")
+
+    if mode == "trodo":
+        active = enable_auto_instrument(processor)
+    elif mode == "otlp":
+        active = _setup_otlp_mode(
+            site_id=site_id,
+            endpoint=endpoint,
+            service_name=service_name,
+            disable=disable_instrumentations or [],
+            processor=processor,
+        )
+    else:
+        raise ValueError(f"register_otel: unknown mode {mode!r}")
+
+    _registered = RegisterOtelResult(
+        mode=mode, active_instrumentations=active, fresh=True
+    )
+    return _registered
+
+
+def _reset_for_tests() -> None:
+    """Reset internal state — for tests only. Not exported from __init__.py."""
+    global _registered
+    _registered = None
+    _reset_transport_for_tests()
+
+
+# ---------------------------------------------------------------------------
+# 'otlp' mode setup
+# ---------------------------------------------------------------------------
+
+
+def _setup_otlp_mode(
+    *,
+    site_id: str,
+    endpoint: str,
+    service_name: str,
+    disable: List[str],
+    processor: TrodoSpanProcessor,
+) -> List[str]:
+    """Lazy-import OTel SDK + protobuf exporter; emit friendly install hint
+    if not installed (only users who pick 'otlp' mode need them)."""
+    try:
+        from opentelemetry import trace as otel_trace
+        from opentelemetry.trace import Status, StatusCode, use_span
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+            OTLPSpanExporter,
+        )
+    except ImportError as e:
+        raise RuntimeError(
+            "register_otel(mode='otlp') requires the OTel SDK + protobuf "
+            "exporter. Install with:\n\n"
+            "  pip install 'trodo-python[otlp]'\n\n"
+            "or directly:\n\n"
+            "  pip install opentelemetry-sdk "
+            "opentelemetry-exporter-otlp-proto-http\n\n"
+            f"Original error: {e}",
+        ) from e
+
+    exporter = OTLPSpanExporter(
+        endpoint=f"{endpoint}/v1/traces",
+        headers={"Authorization": f"Bearer {site_id}"},
+    )
+    batch_processor = BatchSpanProcessor(exporter)
+
+    # Coexistence: if a non-default TracerProvider is already registered,
+    # attach our exporter to it instead of replacing it.
+    existing = otel_trace.get_tracer_provider()
+    existing_class = type(existing).__name__
+    if existing_class not in ("ProxyTracerProvider", "NoOpTracerProvider"):
+        # User's pipeline owns the provider — just attach our processor.
+        if hasattr(existing, "add_span_processor"):
+            existing.add_span_processor(batch_processor)
+        # Auto-instrumentations are presumably already wired by the existing
+        # pipeline. We still set the transport so wrap_agent dispatches.
+        set_otel_transport(
+            otel_trace.get_tracer("trodo-agent"),
+            use_span=use_span,
+            status_cls=Status,
+            status_code=StatusCode,
+        )
+        return _build_instrumentations(disable)
+
+    # Fresh pipeline.
+    resource = Resource.create({
+        "service.name": service_name,
+        "trodo.sdk.mode": "otlp",
+    })
+    provider = TracerProvider(resource=resource)
+    provider.add_span_processor(batch_processor)
+    otel_trace.set_tracer_provider(provider)
+
+    active = _build_instrumentations(disable)
+
+    # Activate the OTel transport so wrap_agent / span dispatch via tracer.
+    set_otel_transport(otel_trace.get_tracer("trodo-agent"))
+    return active
+
+
+def _build_instrumentations(disable: List[str]) -> List[str]:
+    """Best-effort install of OTel auto-instrumentations.
+
+    Mirrors auto_instrument.py's loader list but instruments via the OTel
+    tracer (which is now configured to ship to Trodo via OTLP), not via
+    TrodoSpanProcessor's adapter.
+    """
+    disabled = set(disable)
+    active: List[str] = []
+    candidates = [
+        ("anthropic", "opentelemetry.instrumentation.anthropic", "AnthropicInstrumentor"),
+        ("openai", "opentelemetry.instrumentation.openai", "OpenAIInstrumentor"),
+        ("langchain", "opentelemetry.instrumentation.langchain", "LangChainInstrumentor"),
+        ("llama-index", "opentelemetry.instrumentation.llamaindex", "LlamaIndexInstrumentor"),
+        ("bedrock", "opentelemetry.instrumentation.bedrock", "BedrockInstrumentor"),
+        ("cohere", "opentelemetry.instrumentation.cohere", "CohereInstrumentor"),
+        ("google-generativeai", "opentelemetry.instrumentation.google_generativeai", "GoogleGenerativeAiInstrumentor"),
+        ("vertexai", "opentelemetry.instrumentation.vertexai", "VertexAIInstrumentor"),
+        ("requests", "opentelemetry.instrumentation.requests", "RequestsInstrumentor"),
+        ("httpx", "opentelemetry.instrumentation.httpx", "HTTPXClientInstrumentor"),
+    ]
+    for short_id, mod_path, cls_name in candidates:
+        if short_id in disabled:
+            continue
+        try:
+            mod = __import__(mod_path, fromlist=[cls_name])
+            getattr(mod, cls_name)().instrument()
+            active.append(short_id)
+        except Exception:
+            # Package not installed or instrumentation already attached.
+            pass
+    return active

trodo_python-2.4.0/trodo/otel/transport.py

@@ -0,0 +1,64 @@
+"""
+Transport mode + OTel tracer registry for wrap_agent / span dispatch.
+
+Set by register_otel() at startup. Read by wrap_agent / span to decide whether
+to use the legacy TrodoSpanProcessor + Trodo HTTP API path, or to route
+through an OTel tracer (so auto-instrumented children join the same OTel
+trace and the backend OTLP controller groups them into one run).
+
+Default state: 'trodo' mode + None tracer = legacy behavior, identical to
+the pre-2.4.0 SDK. Existing 2.3.x users see no change.
+"""
+from __future__ import annotations
+from typing import Any, Optional
+
+# Transport state — module-level singletons.
+_mode: str = "trodo"  # 'trodo' | 'otlp'
+_tracer: Optional[Any] = None
+# Optional helpers loaded once at register_otel time. Stored here so
+# wrap_agent / span don't have to do `from opentelemetry import ...` inside
+# the hot path (which would force opentelemetry to be installed even in tests
+# that mock the tracer).
+_use_span: Optional[Any] = None  # callable: (span, end_on_exit=False) -> ContextManager
+_status_cls: Optional[Any] = None  # opentelemetry.trace.Status (or shim)
+_status_code: Optional[Any] = None  # opentelemetry.trace.StatusCode (or shim)
+
+
+def get_transport_mode() -> str:
+    """Read by wrap_agent / span. Returns 'trodo' if register_otel never called."""
+    return _mode
+
+
+def get_otel_tracer() -> Optional[Any]:
+    """Read by wrap_agent / span in 'otlp' mode. None when transport is 'trodo'."""
+    return _tracer
+
+
+def get_otel_helpers() -> tuple:
+    """Returns (use_span, Status, StatusCode) — all callable, all may be None
+    when the tracer was set without helpers (e.g. in tests)."""
+    return _use_span, _status_cls, _status_code
+
+
+def set_otel_transport(tracer: Any, *, use_span=None, status_cls=None, status_code=None) -> None:
+    """Internal: register_otel calls this once mode='otlp' setup completes.
+
+    Helpers are optional so tests can stub a tracer without installing the
+    full opentelemetry stack.
+    """
+    global _mode, _tracer, _use_span, _status_cls, _status_code
+    _mode = "otlp"
+    _tracer = tracer
+    _use_span = use_span
+    _status_cls = status_cls
+    _status_code = status_code
+
+
+def _reset_transport_for_tests() -> None:
+    """Reset for tests. Not exported from trodo/__init__.py."""
+    global _mode, _tracer, _use_span, _status_cls, _status_code
+    _mode = "trodo"
+    _tracer = None
+    _use_span = None
+    _status_cls = None
+    _status_code = None

{trodo_python-2.3.0 → trodo_python-2.4.0}/trodo/otel/wrap_agent.py

@@ -32,6 +32,30 @@ from typing import Any, Callable, Dict, Optional
 
 from .context import ActiveSpanContext, get_active_context, run_with_context
 from .processor import TrodoSpanProcessor, TrodoRun, TrodoSpan
+from .transport import get_transport_mode, get_otel_tracer, get_otel_helpers
+
+
+def _hex_to_uuid(hex_str: str) -> str:
+    """Format a 32-char hex (OTel traceId) into a UUID. Mirrors
+    backend/agentOtlpController.hexToUuid so the run_id returned to the user
+    matches the run_id the backend computes from the OTLP payload."""
+    h = hex_str.replace("-", "")
+    if len(h) != 32:
+        return str(uuid.uuid4())
+    return f"{h[0:8]}-{h[8:12]}-{h[12:16]}-{h[16:20]}-{h[20:32]}"
+
+
+def _serialize_attr(value: Any) -> Any:
+    """Coerce a Python value into something OTel attribute setters accept
+    (str / int / float / bool). Complex objects → JSON string."""
+    if value is None:
+        return ""
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    try:
+        return json.dumps(value, default=str)
+    except Exception:
+        return str(value)
 
 
 def _now_iso() -> str:
@@ -262,8 +286,27 @@ class wrap_agent:
         self._started_ms: float = 0.0
         self._started_iso: str = ""
         self.handle: Optional[RunHandle] = None
+        # OTel-mode state — populated only when transport mode is 'otlp'.
+        self._otel_span: Optional[Any] = None
+        self._otel_token: Optional[Any] = None
 
     def __enter__(self) -> RunHandle:
+        # Dispatch: 'otlp' transport routes through OTel tracer so auto-
+        # instrumented children (Anthropic / LangChain) join the same trace.
+        if get_transport_mode() == "otlp" and get_otel_tracer() is not None:
+            return self._enter_otel()
+        return self._enter_trodo()
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._otel_span is not None:
+            return self._exit_otel(exc_type, exc, tb)
+        return self._exit_trodo(exc_type, exc, tb)
+
+    # ----------------------------------------------------------------------
+    # Legacy 'trodo' transport — TrodoSpanProcessor + Trodo HTTP API path.
+    # ----------------------------------------------------------------------
+
+    def _enter_trodo(self) -> RunHandle:
         run_id = str(uuid.uuid4())
         root_span_id = str(uuid.uuid4())
         self._started_iso = _now_iso()
@@ -281,7 +324,7 @@ class wrap_agent:
         self._ctx_mgr.__enter__()
         return self.handle
 
-    def __exit__(self, exc_type, exc, tb) -> None:
+    def _exit_trodo(self, exc_type, exc, tb) -> None:
         assert self.handle is not None
         ended_iso = _now_iso()
         duration_ms = int(time.time() * 1000.0 - self._started_ms)
@@ -321,6 +364,71 @@ class wrap_agent:
                 self._ctx_mgr.__exit__(exc_type, exc, tb)
         return None
 
+    # ----------------------------------------------------------------------
+    # 'otlp' transport — OTel tracer.start_as_current_span path.
+    # ----------------------------------------------------------------------
+
+    def _enter_otel(self) -> RunHandle:
+        tracer = get_otel_tracer()
+        otel_span = tracer.start_span(self._agent_name)
+        # Make this span the current span for the duration of the with-block
+        # so auto-instrumented children attach to it via OTel context. The
+        # use_span helper is captured at register_otel time so wrap_agent
+        # doesn't need to import opentelemetry at runtime — keeps the test
+        # path mockable and the dependency truly optional in 'trodo' mode.
+        use_span_helper, _, _ = get_otel_helpers()
+        if use_span_helper is not None:
+            cm = use_span_helper(otel_span, end_on_exit=False)
+            cm.__enter__()
+            self._otel_token = cm  # store CM so __exit__ can release the context
+
+        trace_id_int = otel_span.get_span_context().trace_id
+        trace_id_hex = format(trace_id_int, "032x") if isinstance(trace_id_int, int) else str(trace_id_int)
+        run_id = _hex_to_uuid(trace_id_hex)
+
+        otel_span.set_attribute("trodo.agent_name", self._agent_name)
+        if self._distinct_id:
+            otel_span.set_attribute("trodo.distinct_id", str(self._distinct_id))
+        if self._conversation_id:
+            otel_span.set_attribute("trodo.conversation_id", str(self._conversation_id))
+        if self._parent_run_id:
+            otel_span.set_attribute("trodo.parent_run_id", str(self._parent_run_id))
+        if self._metadata:
+            for k, v in self._metadata.items():
+                otel_span.set_attribute(f"trodo.metadata.{k}", _serialize_attr(v))
+
+        self._otel_span = otel_span
+        self.handle = RunHandle(run_id, self._agent_name)
+        return self.handle
+
+    def _exit_otel(self, exc_type, exc, tb) -> None:
+        assert self.handle is not None
+        assert self._otel_span is not None
+        otel_span = self._otel_span
+        try:
+            if self.handle.input is not None:
+                otel_span.set_attribute("ai.prompt", self.handle.input)
+            if self.handle.output is not None:
+                otel_span.set_attribute("ai.response.text", self.handle.output)
+            for k, v in self.handle.metadata.items():
+                otel_span.set_attribute(f"trodo.metadata.{k}", _serialize_attr(v))
+            if exc is not None:
+                otel_span.record_exception(exc)
+                _, status_cls, status_code = get_otel_helpers()
+                if status_cls is not None and status_code is not None:
+                    otel_span.set_status(status_cls(status_code.ERROR, _truncate(str(exc), 4_000) or ""))
+        finally:
+            otel_span.end()
+            # Best-effort close of the use_span CM if it was created.
+            if self._otel_token is not None:
+                try:
+                    self._otel_token.__exit__(exc_type, exc, tb)  # type: ignore[union-attr]
+                except Exception:
+                    pass
+            self._otel_span = None
+            self._otel_token = None
+        return None
+
 
 class join_run:
     """Join an existing agent run owned by a remote service.

{trodo_python-2.3.0 → trodo_python-2.4.0}/trodo/session/server_session.py

@@ -71,4 +71,5 @@ def build_session_payload(session: ServerSession) -> Dict[str, Any]:
         "utm_id": None,
         "visited_pages": [],
         "active_time_ms": 0,
+        "is_server_session": True,
     }

trodo_python-2.3.0/README.md → trodo_python-2.4.0/trodo_python.egg-info/PKG-INFO

@@ -1,3 +1,34 @@
+Metadata-Version: 2.4
+Name: trodo-python
+Version: 2.4.0
+Summary: Trodo Analytics SDK for Python — server-side event tracking
+License: ISC
+Keywords: analytics,tracking,trodo,server-side
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: async
+Requires-Dist: httpx>=0.27.0; extra == "async"
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "otlp"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otlp"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == "otlp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: responses>=0.25.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+
 # trodo-python
 
 Server-side Python SDK for [Trodo Analytics](https://trodo.ai). Track backend events, identify users, manage people/groups, and instrument AI agents — all unified with your frontend data under the same `site_id`.
@@ -10,6 +41,39 @@ pip install trodo-python
 
 Requires Python 3.8+.
 
+## OpenTelemetry / OTLP path (NEW in 2.4.0)
+
+Already running OTel? Skip the Trodo SDK install entirely and point your existing pipeline at Trodo. Two env vars:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://sdkapi.trodo.ai
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${TRODO_SITE_ID}"
+```
+
+The Bearer token is your **site_id** — same value you'd pass to `trodo.init(site_id=...)`. Get it from the [Integration Manager](https://app.trodo.ai/dashboard/integrations).
+
+Use this when **you already run OTel** (Datadog, Jaeger, Honeycomb) and want Trodo as an additional destination. Install `trodo-python` and call `trodo.register_otel(site_id=..., mode='otlp')` to attach our OTLP exporter without replacing your existing setup. `wrap_agent` then routes through OTel so auto-instrumented children share the same trace.
+
+```python
+# At app startup (after your existing OTel provider is registered)
+import os, trodo
+
+trodo.register_otel(
+    site_id=os.environ['TRODO_SITE_ID'],
+    mode='otlp',
+)
+```
+
+`mode='otlp'` requires the optional `[otlp]` extras:
+
+```bash
+pip install 'trodo-python[otlp]'
+```
+
+The SDK raises a friendly install hint if you call `mode='otlp'` without them.
+
+For richer Trodo features on top (`wrap_agent`, `feedback`, `track_mcp`), continue with the SDK quick start below.
+
 ## Quick Start
 
 ```python

{trodo_python-2.3.0 → trodo_python-2.4.0}/trodo_python.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 tests/test_cross_process_session.py
 tests/test_end_run.py
 tests/test_processor_methods.py
+tests/test_register_otel.py
 tests/test_start_run.py
 tests/test_wrap_agent_unchanged.py
 trodo/__init__.py
@@ -23,6 +24,8 @@ trodo/otel/auto_instrument.py
 trodo/otel/context.py
 trodo/otel/helpers.py
 trodo/otel/processor.py
+trodo/otel/register.py
+trodo/otel/transport.py
 trodo/otel/wrap_agent.py
 trodo/queue/__init__.py
 trodo/queue/batch_flusher.py

trodo_python-2.4.0/trodo_python.egg-info/requires.txt

@@ -0,0 +1,15 @@
+requests>=2.28.0
+
+[async]
+httpx>=0.27.0
+
+[dev]
+pytest>=7.0
+pytest-cov
+responses>=0.25.0
+httpx>=0.27.0
+
+[otlp]
+opentelemetry-api>=1.20.0
+opentelemetry-sdk>=1.20.0
+opentelemetry-exporter-otlp-proto-http>=1.20.0

trodo_python-2.3.0/trodo_python.egg-info/requires.txt

@@ -1,10 +0,0 @@
-requests>=2.28.0
-
-[async]
-httpx>=0.27.0
-
-[dev]
-pytest>=7.0
-pytest-cov
-responses>=0.25.0
-httpx>=0.27.0