trodo-python 2.8.0__tar.gz → 2.9.0__tar.gz

{trodo_python-2.8.0 → trodo_python-2.9.0}/PKG-INFO

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

{trodo_python-2.8.0 → trodo_python-2.9.0}/pyproject.toml

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

trodo_python-2.9.0/tests/test_anon_distinct_id.py

@@ -0,0 +1,100 @@
+"""Anonymous distinct_id minting on agent surfaces.
+
+When the caller doesn't pass ``distinct_id``, the SDK mints an
+``anon_<ts>_python_<uuid>_<rand>`` id so:
+
+* the agent_runs row always lands with a non-null distinct_id,
+* the RunHandle exposes the same id so callers can bind
+  ``trodo.feedback(distinct_id=...)`` later,
+* older backends without identity-resolution still attribute the row.
+"""
+from __future__ import annotations
+
+import re
+
+from trodo.otel.wrap_agent import _mint_anon_distinct_id, start_run, wrap_agent
+
+
+ANON_RE = re.compile(r"^anon_\d+_python_")
+
+
+def test_mint_anon_distinct_id_shape():
+    a = _mint_anon_distinct_id()
+    assert ANON_RE.match(a)
+
+
+def test_mint_anon_distinct_id_unique_under_load():
+    ids = {_mint_anon_distinct_id() for _ in range(1000)}
+    assert len(ids) == 1000
+
+
+def test_wrap_agent_mints_anon_when_distinct_id_omitted(processor, http):
+    observed = {}
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="chat",
+    ) as run:
+        observed["distinct_id"] = run.distinct_id
+        run.set_output("done")
+
+    assert ANON_RE.match(observed["distinct_id"])
+    assert len(http.run_ingest) == 1
+    assert http.run_ingest[0]["run"]["distinct_id"] == observed["distinct_id"]
+
+
+def test_wrap_agent_respects_explicit_distinct_id(processor, http):
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="chat",
+        distinct_id="user-42",
+    ) as run:
+        assert run.distinct_id == "user-42"
+
+    assert http.run_ingest[0]["run"]["distinct_id"] == "user-42"
+
+
+def test_wrap_agent_mints_different_anon_ids_across_calls(processor, http):
+    seen = []
+    for _ in range(3):
+        with wrap_agent(
+            processor=processor,
+            team_site_id="site-x",
+            agent_name="chat",
+        ) as run:
+            seen.append(run.distinct_id)
+    assert len(set(seen)) == 3
+
+
+def test_wrap_agent_still_mints_anon_on_error(processor, http):
+    import pytest
+    with pytest.raises(ValueError):
+        with wrap_agent(
+            processor=processor,
+            team_site_id="site-x",
+            agent_name="chat",
+        ) as _run:
+            raise ValueError("boom")
+
+    assert len(http.run_ingest) == 1
+    payload = http.run_ingest[0]["run"]
+    assert payload["status"] == "error"
+    assert ANON_RE.match(payload["distinct_id"])
+
+
+def test_start_run_mints_anon_when_distinct_id_omitted(processor, http):
+    start_run(processor=processor, agent_name="external_session")
+    assert len(http.run_start) == 1
+    run = http.run_start[0]["run"]
+    assert ANON_RE.match(run["distinct_id"])
+
+
+def test_start_run_respects_explicit_distinct_id(processor, http):
+    start_run(
+        processor=processor,
+        agent_name="external_session",
+        distinct_id="user-7",
+    )
+    run = http.run_start[0]["run"]
+    assert run["distinct_id"] == "user-7"

trodo_python-2.9.0/tests/test_error_enrichment.py

@@ -0,0 +1,84 @@
+"""Rich error instrumentation (v2.9.0).
+
+Proves thrown errors surface error TYPE, HTTP/provider STATUS CODE, STACK
+TRACE, and severity LEVEL on both spans and runs — Langfuse parity — instead
+of only a status + message.
+"""
+from __future__ import annotations
+
+import pytest
+
+from trodo.otel.wrap_agent import wrap_agent, span, describe_error
+
+
+class RateLimitError(Exception):
+    """Stand-in for an OpenAI/Anthropic SDK error with an HTTP status + code."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.status = 429
+        self.code = "rate_limit_exceeded"
+
+
+def test_describe_error_extracts_type_status_and_stack():
+    try:
+        raise RateLimitError("rate limit exceeded")
+    except RateLimitError as e:
+        info = describe_error(type(e), e, e.__traceback__)
+    assert info["error_type"] == "RateLimitError"
+    assert info["error_message"] == "rate limit exceeded"
+    assert info["status_code"] == "429"  # HTTP status wins over .code
+    assert info["stack_trace"] and "RateLimitError" in info["stack_trace"]
+    assert info["level"] == "error"
+
+
+def test_describe_error_falls_back_to_response_status():
+    class Resp:
+        status_code = 503
+
+    try:
+        e = RuntimeError("upstream down")
+        e.response = Resp()  # type: ignore[attr-defined]
+        raise e
+    except RuntimeError as ex:
+        info = describe_error(type(ex), ex, ex.__traceback__)
+    assert info["error_type"] == "RuntimeError"
+    assert info["status_code"] == "503"
+
+
+def test_errored_span_and_run_carry_rich_error_fields(processor, http):
+    with pytest.raises(RateLimitError):
+        with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as run:
+            run.set_input("query")
+            with span("call-model", kind="llm"):
+                raise RateLimitError("rate limit exceeded")
+
+    ingest = http.run_ingest[0]
+    run_payload = ingest["run"]
+    spans = ingest.get("spans", [])
+    errored = next(s for s in spans if s["status"] == "error")
+
+    assert errored["error_type"] == "RateLimitError"
+    assert errored["error_message"] == "rate limit exceeded"
+    assert errored["status_code"] == "429"
+    assert "RateLimitError" in errored["stack_trace"]
+    assert errored["level"] == "error"
+
+    assert run_payload["status"] == "error"
+    assert run_payload["level"] == "error"
+    assert run_payload["error_type"] == "RateLimitError"
+    assert "rate limit exceeded" in run_payload["error_summary"]
+
+
+def test_healthy_span_omits_error_fields(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("ok-step", kind="generic"):
+            pass
+
+    spans = http.run_ingest[0].get("spans", [])
+    ok = next(s for s in spans if s["name"] == "ok-step")
+    assert ok["status"] == "ok"
+    # to_dict() drops None fields, so error keys must be absent entirely.
+    assert "error_type" not in ok
+    assert "status_code" not in ok
+    assert "stack_trace" not in ok

{trodo_python-2.8.0 → trodo_python-2.9.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.8.0"
+__version__ = "2.9.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 

{trodo_python-2.8.0 → trodo_python-2.9.0}/trodo/otel/auto_instrument.py

@@ -22,6 +22,13 @@ def _hr_to_iso(nanos: Optional[int]) -> Optional[str]:
     return datetime.fromtimestamp(nanos / 1e9, tz=timezone.utc).isoformat().replace("+00:00", "Z")
 
 
+def _trunc(s: Any, max_len: int) -> Optional[str]:
+    if s is None:
+        return None
+    s = str(s)
+    return s[:max_len] if len(s) > max_len else s
+
+
 def _infer_kind(attrs: Dict[str, Any]) -> str:
     if not attrs:
         return "generic"
@@ -111,6 +118,29 @@ def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
     except Exception:
         ok = "error" if (status_code and str(status_code).endswith("ERROR")) else "ok"
 
+    # Rich error detail. The real exception class + stacktrace live in the OTel
+    # `exception` event (record_exception — emitted by the Anthropic/OpenAI/
+    # LangChain instrumentors), NOT span.status. The old bridge read only the
+    # status code and dropped all of it.
+    status_desc = getattr(status, "description", None)
+    exc_attrs: Dict[str, Any] = {}
+    for ev in (getattr(otel_span, "events", None) or []):
+        if getattr(ev, "name", None) == "exception":
+            exc_attrs = dict(getattr(ev, "attributes", {}) or {})
+            break
+    err_type = exc_attrs.get("exception.type") or attrs.get("exception.type") or attrs.get("error.type")
+    err_msg = exc_attrs.get("exception.message") or attrs.get("exception.message") or status_desc
+    err_stack = exc_attrs.get("exception.stacktrace") or attrs.get("exception.stacktrace")
+    status_code_val = (
+        attrs.get("http.response.status_code")
+        or attrs.get("http.status_code")
+        or attrs.get("gen_ai.response.status_code")
+        or attrs.get("error.code")
+    )
+    has_error = ok == "error" or err_type is not None
+    ok = "error" if has_error else "ok"
+    level = "error" if has_error else "default"
+
     # Accept both stable and experimental GenAI semconv keys.
     in_toks = (
         attrs.get("gen_ai.usage.input_tokens")
@@ -138,6 +168,11 @@ def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
         kind=kind,
         name=getattr(otel_span, "name", kind),
         status=ok,
+        level=level,
+        error_type=_trunc(err_type, 128) if err_type else None,
+        error_message=_trunc(err_msg, 4_000) if err_msg else None,
+        status_code=_trunc(status_code_val, 32) if status_code_val is not None else None,
+        stack_trace=_trunc(err_stack, 20_000) if err_stack else None,
         started_at=started_at,
         ended_at=ended_at,
         duration_ms=duration_ms,

{trodo_python-2.8.0 → trodo_python-2.9.0}/trodo/otel/helpers.py

@@ -413,6 +413,7 @@ def track_mcp(
         "kind": "tool",
         "name": f"tool.{tool}",
         "status": status,
+        "level": "error" if error else "default",
         "input": _stringify({"tool": tool, "params": input}) if input is not None else None,
         "output": _stringify(output_to_record),
         "tool_name": tool,

{trodo_python-2.8.0 → trodo_python-2.9.0}/trodo/otel/processor.py

@@ -20,12 +20,18 @@ class TrodoRun:
     conversation_id: Optional[str] = None
     parent_run_id: Optional[str] = None
     status: str = "ok"  # 'running' | 'ok' | 'error'
+    # Severity (Langfuse parity): 'debug' | 'default' | 'warning' | 'error'.
+    # Optional — backend derives it from status when omitted.
+    level: Optional[str] = None
     input: Optional[Union[str, Dict[str, Any]]] = None
     output: Optional[Union[str, Dict[str, Any]]] = None
     started_at: Optional[str] = None
     ended_at: Optional[str] = None
     duration_ms: Optional[int] = None
     error_summary: Optional[str] = None
+    # Exception class of the run-level failure (runs previously only had the
+    # free-text error_summary).
+    error_type: Optional[str] = None
     metadata: Optional[Dict[str, Any]] = None
     # Aggregates summed from child spans at finalisation.
     total_tokens_in: Optional[int] = None
@@ -47,6 +53,8 @@ class TrodoSpan:
     kind: str = "generic"  # 'llm' | 'tool' | 'agent' | 'retrieval' | 'generic'
     name: str = ""
     status: str = "ok"
+    # Severity (Langfuse parity): 'debug' | 'default' | 'warning' | 'error'.
+    level: Optional[str] = None
     started_at: Optional[str] = None
     ended_at: Optional[str] = None
     duration_ms: Optional[int] = None
@@ -54,6 +62,10 @@ class TrodoSpan:
     output: Optional[Union[str, Dict[str, Any]]] = None
     error_type: Optional[str] = None
     error_message: Optional[str] = None
+    # HTTP/provider status code (e.g. '429', 'rate_limit_exceeded').
+    status_code: Optional[str] = None
+    # Truncated exception stacktrace.
+    stack_trace: Optional[str] = None
     model: Optional[str] = None
     provider: Optional[str] = None
     input_tokens: Optional[int] = None

{trodo_python-2.8.0 → trodo_python-2.9.0}/trodo/otel/wrap_agent.py

@@ -26,6 +26,7 @@ from __future__ import annotations
 
 import json
 import time
+import traceback
 import uuid
 from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Optional, Union
@@ -79,6 +80,54 @@ def _truncate(value: Any, max_len: int = _MAX_VALUE_LEN) -> Optional[str]:
     return s[:max_len] if len(s) > max_len else s
 
 
+def describe_error(exc_type, exc, tb=None) -> Dict[str, Optional[str]]:
+    """Extract rich error detail from a caught exception so spans carry error
+    TYPE, HTTP/provider STATUS CODE, and STACK TRACE — not just a message.
+
+    Works generically across provider SDKs: OpenAI (``exc.status`` /
+    ``exc.code``), Anthropic (``exc.status``), httpx/requests
+    (``exc.response.status_code``), and stdlib errors (``exc.errno``). Never
+    raises. Returns keys: error_type, error_message, status_code, stack_trace,
+    level.
+    """
+    if exc is None:
+        return {"error_type": None, "error_message": None, "status_code": None,
+                "stack_trace": None, "level": "error"}
+    error_type = getattr(exc_type, "__name__", None) or type(exc).__name__
+    error_message = _truncate(str(exc), 4_000)
+
+    status_code: Optional[str] = None
+    # HTTP status first (numeric), then a provider/system error code.
+    for attr in ("status", "status_code"):
+        v = getattr(exc, attr, None)
+        if v is not None:
+            status_code = str(v)[:32]
+            break
+    if status_code is None:
+        resp = getattr(exc, "response", None)
+        rc = getattr(resp, "status_code", None) if resp is not None else None
+        if rc is not None:
+            status_code = str(rc)[:32]
+    if status_code is None:
+        code = getattr(exc, "code", None) or getattr(exc, "errno", None)
+        if code is not None:
+            status_code = str(code)[:32]
+
+    stack_trace: Optional[str] = None
+    try:
+        stack_trace = _truncate("".join(traceback.format_exception(exc_type, exc, tb)), 20_000)
+    except Exception:
+        stack_trace = None
+
+    return {
+        "error_type": (error_type or "Error")[:128],
+        "error_message": error_message,
+        "status_code": status_code,
+        "stack_trace": stack_trace,
+        "level": "error",
+    }
+
+
 def _prepare_value(value: Any, max_len: int = _MAX_VALUE_LEN) -> Optional[Union[str, Dict[str, Any]]]:
     """Prepare a value for storage in the JSONB input/output column.
 
@@ -204,6 +253,15 @@ class SpanHandle:
         self.cost_details: Optional[Dict[str, float]] = None
         self.temperature: Optional[float] = None
         self.tool_name: Optional[str] = None
+        # Severity for this span (Langfuse parity). Leave None for the default
+        # behaviour (backend derives 'error' on a thrown exception, else
+        # 'default'). Set 'warning' for a recovered/retried step, 'debug' for
+        # verbose spans.
+        self.level: Optional[str] = None
+
+    def set_level(self, level: str) -> None:
+        """Mark this span's severity (does not change ok/error status)."""
+        self.level = level
 
     def set_input(self, value: Any) -> None:
         self.input = _prepare_value(value)
@@ -419,9 +477,8 @@ class wrap_agent:
         ended_iso = _now_iso()
         duration_ms = int(time.time() * 1000.0 - self._started_ms)
         status = "error" if exc is not None else "ok"
-        error_summary = None
-        if exc is not None:
-            error_summary = _truncate(str(exc), 4_000)
+        einfo = describe_error(exc_type, exc, tb) if exc is not None else None
+        error_summary = einfo["error_message"] if einfo else None
 
         pending = self._processor.get_pending(self.handle.run_id)
         agg = _aggregate(pending)
@@ -433,12 +490,14 @@ class wrap_agent:
             conversation_id=self._conversation_id,
             parent_run_id=self._parent_run_id,
             status=status,
+            level="error" if exc is not None else None,
             input=self.handle.input,
             output=self.handle.output,
             started_at=self._started_iso,
             ended_at=ended_iso,
             duration_ms=duration_ms,
             error_summary=error_summary,
+            error_type=einfo["error_type"] if einfo else None,
             metadata={**(self._metadata or {}), **self.handle.metadata} or None,
             total_tokens_in=agg["total_tokens_in"],
             total_tokens_out=agg["total_tokens_out"],
@@ -584,8 +643,8 @@ class join_run:
         ended_iso = _now_iso()
         duration_ms = int(time.time() * 1000.0 - self._started_ms)
         status = "error" if exc is not None else "ok"
-        error_type = exc_type.__name__ if exc_type else None
-        error_message = _truncate(str(exc), 4_000) if exc else None
+        einfo = describe_error(exc_type, exc, tb) if exc is not None else None
+        level = self.handle.level or ("error" if exc is not None else None)
 
         trodo_span = TrodoSpan(
             span_id=self._span_id,
@@ -594,13 +653,16 @@ class join_run:
             kind=self._kind,
             name=self._name,
             status=status,
+            level=level,
             started_at=self._started_iso,
             ended_at=ended_iso,
             duration_ms=duration_ms,
             input=self.handle.input,
             output=self.handle.output,
-            error_type=error_type,
-            error_message=error_message,
+            error_type=einfo["error_type"] if einfo else None,
+            error_message=einfo["error_message"] if einfo else None,
+            status_code=einfo["status_code"] if einfo else None,
+            stack_trace=einfo["stack_trace"] if einfo else None,
             model=self.handle.model,
             provider=self.handle.provider,
             input_tokens=self.handle.input_tokens,
@@ -676,8 +738,8 @@ class span:
         ended_iso = _now_iso()
         duration_ms = int(time.time() * 1000.0 - self._started_ms)
         status = "error" if exc is not None else "ok"
-        error_type = exc_type.__name__ if exc_type else None
-        error_message = _truncate(str(exc), 4_000) if exc else None
+        einfo = describe_error(exc_type, exc, tb) if exc is not None else None
+        level = self.handle.level or ("error" if exc is not None else None)
 
         trodo_span = TrodoSpan(
             span_id=self._span_id,
@@ -686,13 +748,16 @@ class span:
             kind=self._kind,
             name=self._name,
             status=status,
+            level=level,
             started_at=self._started_iso,
             ended_at=ended_iso,
             duration_ms=duration_ms,
             input=self.handle.input,
             output=self.handle.output,
-            error_type=error_type,
-            error_message=error_message,
+            error_type=einfo["error_type"] if einfo else None,
+            error_message=einfo["error_message"] if einfo else None,
+            status_code=einfo["status_code"] if einfo else None,
+            stack_trace=einfo["stack_trace"] if einfo else None,
             model=self.handle.model,
             provider=self.handle.provider,
             input_tokens=self.handle.input_tokens,

{trodo_python-2.8.0 → trodo_python-2.9.0}/trodo_python.egg-info/PKG-INFO

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

{trodo_python-2.8.0 → trodo_python-2.9.0}/trodo_python.egg-info/SOURCES.txt

@@ -1,9 +1,11 @@
 README.md
 pyproject.toml
+tests/test_anon_distinct_id 2.py
 tests/test_anon_distinct_id.py
 tests/test_auto_instrument_fixes.py
 tests/test_cross_process_session.py
 tests/test_end_run.py
+tests/test_error_enrichment.py
 tests/test_llm_usage_cost.py
 tests/test_processor_methods.py
 tests/test_register_otel.py