trodo-python 2.10.2__tar.gz → 2.10.4__tar.gz

{trodo_python-2.10.2 → trodo_python-2.10.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.10.2
+Version: 2.10.4
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side

{trodo_python-2.10.2 → trodo_python-2.10.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trodo-python"
-version = "2.10.2"
+version = "2.10.4"
 description = "Trodo Analytics SDK for Python — server-side event tracking"
 readme = "README.md"
 license = { text = "ISC" }

{trodo_python-2.10.2 → trodo_python-2.10.4}/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.10.2"
+__version__ = "2.10.4"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 

{trodo_python-2.10.2 → trodo_python-2.10.4}/trodo/client.py

@@ -23,7 +23,11 @@ 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.register import (
+    register_otel as _register_otel,
+    flush_otlp_pipeline as _flush_otlp_pipeline,
+    shutdown_otlp_pipeline as _shutdown_otlp_pipeline,
+)
 from .otel.helpers import (
     tool as tool_decorator,
     track_llm_call as track_llm_call_fn,
@@ -233,6 +237,9 @@ class TrodoClient:
         if self._batch_flusher:
             self._batch_flusher.flush()
         self._span_processor.force_flush()
+        # 'otlp' mode: drain the OTel BatchSpanProcessor too — it batches for
+        # up to 5s, so without this a short-lived process drops its spans.
+        _flush_otlp_pipeline()
 
     def shutdown(self) -> None:
         self._auto_event_manager.disable()
@@ -240,6 +247,7 @@ class TrodoClient:
             self._batch_flusher.stop()
             self._batch_flusher.flush()
         self._span_processor.shutdown()
+        _shutdown_otlp_pipeline()
 
     # --------------------------------------------------------------------------
     # Agent Runs — Lemma-style seamless wrapping

{trodo_python-2.10.2 → trodo_python-2.10.4}/trodo/otel/auto_instrument.py

@@ -9,12 +9,25 @@ lazily and skip anything that isn't installed.
 
 from __future__ import annotations
 
+import sys
 from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 from .context import get_active_context
 from .processor import TrodoSpan, TrodoSpanProcessor
 
+# Always-on, one-shot warnings. Silent skips (missing opentelemetry-sdk) are the
+# #1 cause of "I installed Trodo but see no LLM spans" — surface them even
+# without debug, matching the Node SDK's warnOnce behaviour.
+_WARNED_ONCE: set = set()
+
+
+def _warn_once(key: str, msg: str) -> None:
+    if key in _WARNED_ONCE:
+        return
+    _WARNED_ONCE.add(key)
+    sys.stderr.write(f"[trodo-python] {msg}\n")
+
 
 def _hr_to_iso(nanos: Optional[int]) -> Optional[str]:
     if nanos is None:
@@ -341,14 +354,21 @@ def enable_auto_instrument(
     """Register OTel auto-instrumentations for installed packages.
 
     Returns the list of framework ids that were actually instrumented.
-    Skipped silently if opentelemetry-sdk or the per-framework
-    instrumentation package isn't installed.
+    Emits a one-shot stderr warning if opentelemetry-sdk isn't installed (the
+    #1 silent-failure mode); per-framework instrumentation packages that aren't
+    installed are skipped silently.
     """
     disabled = set(disable or [])
     try:
         from opentelemetry import trace  # type: ignore
         from opentelemetry.sdk.trace import TracerProvider  # type: ignore
     except Exception:
+        _warn_once(
+            "otel-sdk-missing",
+            "auto-instrument: opentelemetry-sdk is not installed — no LLM spans "
+            "will be auto-captured. Install: pip install opentelemetry-sdk "
+            "opentelemetry-api (plus opentelemetry-instrumentation-<provider> per framework).",
+        )
         return []
 
     provider = trace.get_tracer_provider()

{trodo_python-2.10.2 → trodo_python-2.10.4}/trodo/otel/register.py

@@ -36,6 +36,33 @@ class RegisterOtelResult:
 
 _registered: Optional[RegisterOtelResult] = None
 
+# Flush/shutdown handle for the 'otlp'-mode pipeline. Without this, the
+# BatchSpanProcessor created in _setup_otlp_mode (default 5s schedule) is
+# unreachable — trodo.flush()/shutdown() only drained the events batcher and
+# TrodoSpanProcessor, so short-lived processes silently dropped every
+# OTLP-exported span. TrodoClient.flush()/shutdown() call these.
+_otlp_processor: Optional[Any] = None
+
+
+def flush_otlp_pipeline() -> None:
+    """Force-flush the 'otlp'-mode export pipeline. No-op in 'trodo' mode."""
+    if _otlp_processor is not None:
+        try:
+            _otlp_processor.force_flush()
+        except Exception:
+            pass
+
+
+def shutdown_otlp_pipeline() -> None:
+    """Shut down the 'otlp'-mode export pipeline (flushes first). No-op in 'trodo' mode."""
+    global _otlp_processor
+    if _otlp_processor is not None:
+        proc, _otlp_processor = _otlp_processor, None
+        try:
+            proc.shutdown()
+        except Exception:
+            pass
+
 
 def register_otel(
     *,
@@ -86,8 +113,9 @@ def register_otel(
 
 def _reset_for_tests() -> None:
     """Reset internal state — for tests only. Not exported from __init__.py."""
-    global _registered
+    global _registered, _otlp_processor
     _registered = None
+    _otlp_processor = None
     _reset_transport_for_tests()
 
 
@@ -131,6 +159,11 @@ def _setup_otlp_mode(
         headers={"Authorization": f"Bearer {site_id}"},
     )
     batch_processor = BatchSpanProcessor(exporter)
+    # Expose flush/shutdown so trodo.flush()/shutdown() can drain the batch —
+    # BatchSpanProcessor holds spans for up to 5s by default, so without this
+    # a short-lived process exits before the exporter ever sends them.
+    global _otlp_processor
+    _otlp_processor = batch_processor
 
     # Coexistence: if a non-default TracerProvider is already registered,
     # attach our exporter to it instead of replacing it.
@@ -162,7 +195,16 @@ def _setup_otlp_mode(
     active = _build_instrumentations(disable)
 
     # Activate the OTel transport so wrap_agent / span dispatch via tracer.
-    set_otel_transport(otel_trace.get_tracer("trodo-agent"))
+    # Pass the use_span/Status/StatusCode helpers (same as the coexistence
+    # branch above) — without use_span, wrap_agent's root span is never made
+    # current, so trodo.span() children and auto-instrumented spans can't
+    # join its trace, and error status can never be stamped.
+    set_otel_transport(
+        otel_trace.get_tracer("trodo-agent"),
+        use_span=use_span,
+        status_cls=Status,
+        status_code=StatusCode,
+    )
     return active
 
 

{trodo_python-2.10.2 → trodo_python-2.10.4}/trodo/otel/wrap_agent.py

@@ -253,8 +253,14 @@ class RunHandle:
     def set_output(self, value: Any) -> None:
         self.output = _prepare_value(value)
 
-    def set_metadata(self, **kwargs: Any) -> None:
-        self.metadata.update(kwargs)
+    def set_metadata(self, metadata: Optional[Dict[str, Any]] = None, **kwargs: Any) -> None:
+        # Accept a dict (Node parity: setMetadata({...})) and/or keyword args
+        # (set_metadata(key=value)). Previously kwargs-only, which broke code
+        # copied from the Node SDK.
+        if metadata:
+            self.metadata.update(metadata)
+        if kwargs:
+            self.metadata.update(kwargs)
 
     def set_error_summary(self, summary: str, *, type: Optional[str] = None) -> None:
         """Mark the run as errored without raising — e.g. a soft failure the
@@ -636,10 +642,12 @@ class wrap_agent:
         assert self._otel_span is not None
         otel_span = self._otel_span
         try:
+            # OTel attribute values must be primitives — dicts/lists are
+            # rejected (with a warning) and silently dropped. Serialize.
             if self.handle.input is not None:
-                otel_span.set_attribute("ai.prompt", self.handle.input)
+                otel_span.set_attribute("ai.prompt", _serialize_attr(self.handle.input))
             if self.handle.output is not None:
-                otel_span.set_attribute("ai.response.text", self.handle.output)
+                otel_span.set_attribute("ai.response.text", _serialize_attr(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:
@@ -787,8 +795,17 @@ class span:
         self._active: Optional[ActiveSpanContext] = None
         self._span_id: str = ""
         self.handle: Optional[SpanHandle] = None
+        # 'otlp' transport state — populated only when register_otel(mode='otlp').
+        self._otel_span: Optional[Any] = None
+        self._otel_cm: Optional[Any] = None
 
     def __enter__(self) -> SpanHandle:
+        # Dispatch: 'otlp' transport routes through the OTel tracer so this
+        # span joins the wrap_agent root's trace (mirrors Node withSpanOtel).
+        # Without this branch, otlp-mode children hit the "no active run"
+        # no-op below and were silently dropped.
+        if get_transport_mode() == "otlp" and get_otel_tracer() is not None:
+            return self._enter_otel()
         self._active = get_active_context()
         self._span_id = str(uuid.uuid4())
         self.handle = SpanHandle(self._span_id, self._name)
@@ -813,6 +830,8 @@ class span:
         return self.handle
 
     def __exit__(self, exc_type, exc, tb) -> None:
+        if self._otel_span is not None:
+            return self._exit_otel(exc_type, exc, tb)
         if self._active is None or self.handle is None:
             return None
         ended_iso = _now_iso()
@@ -854,3 +873,75 @@ class span:
         if self._ctx_mgr is not None:
             self._ctx_mgr.__exit__(exc_type, exc, tb)
         return None
+
+    # ----------------------------------------------------------------------
+    # 'otlp' transport — OTel tracer path (mirrors Node withSpanOtel).
+    # ----------------------------------------------------------------------
+
+    def _enter_otel(self) -> SpanHandle:
+        tracer = get_otel_tracer()
+        # start_span parents to the CURRENT OTel context — the wrap_agent root
+        # (made current via use_span in _enter_otel of wrap_agent).
+        otel_span = tracer.start_span(self._name)
+        use_span_helper, _, _ = get_otel_helpers()
+        if use_span_helper is not None:
+            self._otel_cm = use_span_helper(otel_span, end_on_exit=False)
+            self._otel_cm.__enter__()
+        self._otel_span = otel_span
+        self._span_id = str(uuid.uuid4())
+        self.handle = SpanHandle(self._span_id, self._name)
+        if self._input is not None:
+            self.handle.input = self._input
+        if self._attributes:
+            self.handle.attributes.update(self._attributes)
+        return self.handle
+
+    def _exit_otel(self, exc_type, exc, tb) -> None:
+        otel_span = self._otel_span
+        h = self.handle
+        try:
+            # Stamp Trodo kind via gen_ai.* / retrieval.* convention so the
+            # backend's kind inference picks it up (same keys as trodo-node).
+            if self._kind == "tool":
+                otel_span.set_attribute("gen_ai.tool.name", h.tool_name or self._name)
+            if self._kind == "retrieval":
+                otel_span.set_attribute("retrieval.query", self._name)
+            if h.input is not None:
+                otel_span.set_attribute("input.value", _serialize_attr(h.input))
+            if h.output is not None:
+                otel_span.set_attribute("output.value", _serialize_attr(h.output))
+            if h.model:
+                otel_span.set_attribute("gen_ai.request.model", h.model)
+            if h.provider:
+                otel_span.set_attribute("gen_ai.system", h.provider)
+            if h.input_tokens is not None:
+                otel_span.set_attribute("gen_ai.usage.input_tokens", h.input_tokens)
+            if h.output_tokens is not None:
+                otel_span.set_attribute("gen_ai.usage.output_tokens", h.output_tokens)
+            if h.cost is not None:
+                otel_span.set_attribute("gen_ai.usage.cost", h.cost)
+            if h.temperature is not None:
+                otel_span.set_attribute("gen_ai.request.temperature", h.temperature)
+            if h.tool_name:
+                otel_span.set_attribute("gen_ai.tool.name", h.tool_name)
+            for k, v in (h.attributes or {}).items():
+                otel_span.set_attribute(f"trodo.span.{k}", _serialize_attr(v))
+            einfo = _resolve_error(h, exc_type, exc, tb)
+            if einfo["status"] == "error":
+                if exc is not None and hasattr(otel_span, "record_exception"):
+                    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, einfo["error_message"] or "")
+                    )
+        finally:
+            otel_span.end()
+            if self._otel_cm is not None:
+                try:
+                    self._otel_cm.__exit__(exc_type, exc, tb)
+                except Exception:
+                    pass
+            self._otel_span = None
+            self._otel_cm = None
+        return None

{trodo_python-2.10.2 → trodo_python-2.10.4}/trodo_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.10.2
+Version: 2.10.4
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side