trodo-python 2.23.4__py3-none-any.whl → 2.24.0__py3-none-any.whl

trodo/__init__.py

@@ -41,7 +41,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.23.4"
+__version__ = "2.24.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -163,6 +163,8 @@ def init(
     auto_instrument: bool = True,
     disable_instrumentations: Optional[List[str]] = None,
     otel_mode: str = "trodo",
+    delivery: str = "auto",
+    delivery_options: Optional[Dict[str, Any]] = None,
 ) -> TrodoClient:
     """Initialise the singleton SDK instance.
 
@@ -171,6 +173,19 @@ def init(
     any other installed opentelemetry-instrumentation-* package, so
     LLM calls emit token/cost spans with no further code.
 
+    ``delivery`` (2.24): how traces reach Trodo.
+      'background' — wrap_agent returns at once; a daemon thread posts queued
+                     runs in batches every second, retries while nobody waits,
+                     and flushes at exit. The default on servers.
+      'immediate'  — the run is sent before wrap_agent returns, with short
+                     retries (≤ 15 s), for platforms that freeze between
+                     requests: Lambda, Cloud Functions, Cloud Run, Vercel.
+      'auto'       — 'immediate' when such a platform's environment variables
+                     are present, otherwise 'background'. Default.
+    ``delivery_options``: flush_interval_s (1), flush_at (50), max_batch_bytes
+    (4 MB), max_queue_items (10,000), max_queue_bytes (64 MB), max_retry_s
+    (600), exit_flush_s (5).
+
     ``disable_instrumentations`` turns OFF specific instrumentors by id
     (e.g. ``['openai']`` when LangChain is your primary framework, to avoid
     double-counting the same model call). Mirrors Node's
@@ -191,6 +206,8 @@ def init(
         auto_instrument=auto_instrument,
         disable_instrumentations=disable_instrumentations,
         otel_mode=otel_mode,
+        delivery=delivery,
+        delivery_options=delivery_options,
     )
     return _client
 

trodo/_version.py

@@ -0,0 +1 @@
+SDK_VERSION = "2.24.0"

trodo/api/endpoints.py

@@ -22,8 +22,11 @@ GROUPS_REMOVE = "/api/sdk/groups/remove_group"
 GROUPS_PROFILE = "/api/sdk/groups/profile"
 # Agent run tracking (Lemma-style, run-centric)
 RUNS_INGEST = "/api/sdk/runs/ingest"
+# Many writes in one request — the background sender (delivery/sender.py).
+BATCH = "/api/sdk/batch"
 RUNS_START = "/api/sdk/runs/start"
 RUNS_BASE = "/api/sdk/runs"  # /runs/{run_id}/end, /spans, /feedback
+SPANS_APPEND = "/api/sdk/spans/append"
 OTLP_TRACES = "/api/sdk/otel/v1/traces"
 # Datasets & experiments
 DATASETS_BASE = "/api/sdk/datasets"  # /datasets/{ref}/items

trodo/api/http_client.py

@@ -11,6 +11,7 @@ import requests
 from ..types import ApiResult, EventPayload
 from . import endpoints
 from ._retry import jittered_backoff, retry_delay
+from .._version import SDK_VERSION
 
 
 class HttpClient:
@@ -82,9 +83,40 @@ class HttpClient:
                 return self._request(path, body, attempt + 1)
             self._log(f"Error: {exc}")
             if self.on_error:
-                self.on_error(exc)
+                try:
+                    self.on_error(exc)
+                except Exception:
+                    pass  # a handler that raises must not surface into user code
             return {}
 
+    def post_raw(
+        self, path: str, body: Dict[str, Any], timeout: Optional[float] = None, gzip_body: bool = True,
+    ) -> tuple:
+        """One attempt, the status told: ``(status, retry_after, parsed_body)``.
+
+        The background sender (delivery/sender.py) decides what to do with a
+        429, a 5xx or a timeout, so unlike ``_request`` this neither retries
+        nor swallows: it raises only on a network error or a timeout. Bodies
+        over 8 KB are gzipped.
+        """
+        import gzip as _gzip
+        import json as _json
+
+        url = f"{self.api_base}{path}"
+        raw = _json.dumps(body, default=str).encode("utf-8")
+        headers: Dict[str, str] = {"User-Agent": f"trodo-python/{SDK_VERSION}"}
+        data = raw
+        if gzip_body and len(raw) > 8 * 1024:
+            data = _gzip.compress(raw)
+            headers["Content-Encoding"] = "gzip"
+        self._log(f"POST {url} ({len(raw)} bytes{', gzip' if 'Content-Encoding' in headers else ''})")
+        resp = self._session.post(url, data=data, headers=headers, timeout=timeout or self.timeout)
+        try:
+            parsed = resp.json() if resp.text else None
+        except Exception:
+            parsed = {"body": resp.text[:300]}
+        return resp.status_code, resp.headers.get("retry-after"), parsed
+
     def _get(
         self, path: str, params: Optional[Dict[str, Any]] = None, attempt: int = 0
     ) -> ApiResult:

trodo/client.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import functools
+import inspect
 from typing import Any, Callable, Dict, List, Optional, Union
 
 from .api.http_client import HttpClient
@@ -14,6 +15,7 @@ from .queue.batch_flusher import BatchFlusher
 from .auto.auto_event_manager import AutoEventManager
 from .user_context import UserContext
 from .otel.processor import TrodoSpanProcessor
+from .delivery.sender import Sender
 from .otel.wrap_agent import (
     wrap_agent as wrap_agent_ctx,
     span as span_ctx,
@@ -61,6 +63,8 @@ class TrodoClient:
         disable_instrumentations: Optional[List[str]] = None,
         otel_mode: str = "trodo",
         max_cached_users: int = 10_000,
+        delivery: str = "auto",
+        delivery_options: Optional[Dict[str, Any]] = None,
     ) -> None:
         if not site_id:
             raise ValueError("trodo-python: site_id is required")
@@ -105,7 +109,11 @@ class TrodoClient:
         # API server. An evicted user is simply rebuilt on next use.
         self._user_context_cache: LruDict[str, UserContext] = LruDict(max_cached_users)
 
-        self._span_processor = TrodoSpanProcessor(http_client=self._http)
+        # Background delivery (2.24): runs and spans are queued and sent by a
+        # daemon thread; 'immediate' on serverless platforms (detected from
+        # the environment when delivery='auto').
+        self._sender = Sender(self._http, mode=delivery, on_error=on_error, debug=debug, **(delivery_options or {}))
+        self._span_processor = TrodoSpanProcessor(http_client=self._http, sender=self._sender)
         if auto_instrument:
             import os
             if os.environ.get("TRODO_LEGACY_INIT") == "1":
@@ -299,10 +307,12 @@ class TrodoClient:
     # Lifecycle
     # --------------------------------------------------------------------------
 
-    def flush(self) -> None:
+    def flush(self, timeout: Optional[float] = None) -> None:
+        """Send everything queued and wait for it (bounded by ``timeout`` seconds, if given)."""
         if self._batch_flusher:
             self._batch_flusher.flush()
         self._span_processor.force_flush()
+        self._sender.flush(timeout)
         # '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()
@@ -313,8 +323,13 @@ class TrodoClient:
             self._batch_flusher.stop()
             self._batch_flusher.flush()
         self._span_processor.shutdown()
+        self._sender.shutdown()
         _shutdown_otlp_pipeline()
 
+    def delivery_stats(self) -> Dict[str, Any]:
+        """What the background sender is doing: queued, in flight, sent, dropped (by reason), paused-until, mode."""
+        return self._sender.stats()
+
     # --------------------------------------------------------------------------
     # Agent Runs — Lemma-style seamless wrapping
     # --------------------------------------------------------------------------
@@ -364,16 +379,31 @@ class TrodoClient:
         """Decorator form of wrap_agent."""
 
         def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
-            @functools.wraps(fn)
-            def wrapper(*args: Any, **kwargs: Any) -> Any:
-                with self.wrap_agent(
+            def _run():
+                return self.wrap_agent(
                     agent_name,
                     distinct_id=distinct_id,
                     conversation_id=conversation_id,
                     parent_run_id=parent_run_id,
                     metadata=metadata,
                     user=user,
-                ) as run:
+                )
+
+            if inspect.iscoroutinefunction(fn):
+                # An ``async def`` agent (2.24). Before, the run closed the
+                # moment the coroutine was created and recorded the coroutine
+                # object as its output.
+                @functools.wraps(fn)
+                async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                    async with _run() as run:
+                        result = await fn(*args, **kwargs)
+                        run.set_output(result)
+                        return result
+                return async_wrapper
+
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                with _run() as run:
                     result = fn(*args, **kwargs)
                     run.set_output(result)
                     return result
@@ -600,7 +630,10 @@ class TrodoClient:
             "distinct_id": distinct_id,
             "attributes": metadata or {},
         }
-        return self._http.post_run_feedback(run_id, payload)
+        # Queued behind the run it belongs to (2.24): never waits on the
+        # network, survives an outage, and lands after its run.
+        self._sender.enqueue({"run_id": run_id, "feedback": payload})
+        return {}
 
     def feedback_props(self, run_id: str, props: FeedbackProps) -> ApiResult:
         """Convenience — pass a FeedbackProps dataclass."""

trodo/delivery/sender.py

@@ -0,0 +1,500 @@
+"""Background delivery of traces (2.24).
+
+Before this, ``wrap_agent`` posted the finished run — and slept through every
+retry and Retry-After — on the caller's thread before handing the agent's
+result back: up to ~90 s added to one agent call when a team was over its
+rate ceiling, the event loop frozen in an asyncio app, and then the trace was
+dropped. Now a finished run (or a flush of spans) goes into this queue and
+the agent returns at once. A daemon thread drains the queue to
+``POST /api/sdk/batch`` every second or 50 items, gzipped.
+
+The rules match what Langfuse, LangSmith, Braintrust, OpenTelemetry, Sentry
+and PostHog have converged on (1 Oct 2026 survey):
+  - bounded queue (10,000 items / 64 MB). Full → the OLDEST are dropped, so
+    the traces being debugged right now survive; drops are counted and
+    reported to the server with the next batch.
+  - retries while nobody waits: 429 pauses the whole sender until
+    Retry-After (a client over its limit delivers late, not never); 5xx, 408
+    and network errors back off (1 s → 60 s) for up to 10 minutes per item,
+    then it is dropped as ``gave_up``; 413 splits the batch, a single
+    oversized item is dropped as ``too_large``; any other 4xx is a bad item:
+    dropped as ``rejected``, reported once.
+  - exit: ``atexit`` flushes (bounded by ``exit_flush_s``).
+  - ``immediate`` mode for platforms that freeze between requests (Lambda,
+    Cloud Functions, Cloud Run, Vercel): the item is sent now, with short
+    retries, on the caller's thread. ``auto`` picks it from the platform's
+    environment variables.
+"""
+
+from __future__ import annotations
+
+import atexit
+import gzip
+import json
+import os
+import random
+import sys
+import threading
+import time
+from collections import deque
+from typing import Any, Callable, Deque, Dict, List, Optional
+
+from ..api import endpoints
+
+Item = Dict[str, Any]
+
+DEFAULTS = dict(
+    flush_interval_s=1.0, flush_at=50, max_batch_bytes=4 * 1024 * 1024,
+    max_queue_items=10_000, max_queue_bytes=64 * 1024 * 1024,
+    max_retry_s=600.0, max_retry_after_s=600.0, immediate_retry_s=15.0,
+    exit_flush_s=5.0, request_timeout_s=20.0,
+)
+_MIN_BACKOFF_S = 1.0
+_MAX_BACKOFF_S = 60.0
+_TRANSIENT = {408, 425, 429, 500, 502, 503, 504}
+
+
+def detect_mode(env: Optional[Dict[str, str]] = None) -> str:
+    """'immediate' on serverless / freeze-between-requests platforms, else 'background'."""
+    e = os.environ if env is None else env
+    if e.get("AWS_LAMBDA_FUNCTION_NAME") or e.get("LAMBDA_TASK_ROOT"):
+        return "immediate"
+    if e.get("FUNCTION_TARGET") or e.get("FUNCTION_NAME") or e.get("K_SERVICE"):
+        return "immediate"  # Cloud Functions / Cloud Run (CPU off between requests)
+    if e.get("NETLIFY") or e.get("VERCEL") or e.get("FUNCTIONS_WORKER_RUNTIME"):
+        return "immediate"
+    return "background"
+
+
+def parse_retry_after_s(value: Optional[str], now: float) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        secs = float(value)
+        return secs if secs > 0 else None
+    except ValueError:
+        pass
+    try:
+        from email.utils import parsedate_to_datetime
+        delta = parsedate_to_datetime(value).timestamp() - now
+        return delta if delta > 0 else None
+    except Exception:
+        return None
+
+
+class _Queued:
+    __slots__ = ("item", "nbytes", "enqueued_at", "first_tried_at", "attempts")
+
+    def __init__(self, item: Item, nbytes: int, enqueued_at: float) -> None:
+        self.item = item
+        self.nbytes = nbytes
+        self.enqueued_at = enqueued_at
+        self.first_tried_at: Optional[float] = None
+        self.attempts = 0
+
+
+class Sender:
+    def __init__(
+        self,
+        http: Any,
+        mode: str = "auto",
+        on_error: Optional[Callable[[Exception], None]] = None,
+        debug: bool = False,
+        now: Callable[[], float] = time.time,
+        sleep: Callable[[float], None] = time.sleep,
+        register_atexit: bool = True,
+        **options: Any,
+    ) -> None:
+        self._http = http
+        self.mode = mode if mode in ("background", "immediate") else detect_mode()
+        self._o = {**DEFAULTS, **{k: v for k, v in options.items() if v is not None}}
+        self._on_error = on_error
+        self._debug = debug
+        self._now = now
+        self._sleep = sleep
+        self._queue: Deque[_Queued] = deque()
+        self._queue_bytes = 0
+        self._lock = threading.Lock()
+        self._wake = threading.Condition(self._lock)
+        self._paused_until: Optional[float] = None
+        self._not_before: float = 0.0  # backoff after a failed batch
+        self._stopped = False
+        self._flush_requested = False
+        self._in_flight = 0
+        self._stats = {"sent": 0, "dropped": 0, "dropped_by_reason": {}}
+        self._unreported = {"count": 0, "by_reason": {}}
+        self._warned_drop = False
+        self._thread: Optional[threading.Thread] = None
+        if self.mode == "background" and register_atexit:
+            atexit.register(self._atexit)
+
+    # ── public ────────────────────────────────────────────────────────────────
+
+    def enqueue(self, item: Item) -> None:
+        """Queue an item. Returns at once in background mode; in immediate mode
+        returns once the item is sent (or given up on)."""
+        if self._stopped:
+            return
+        if self.mode == "immediate":
+            self._send_immediate(item)
+            return
+        nbytes = _size_of(item)
+        if nbytes > self._o["max_batch_bytes"]:
+            self._drop(1, "too_large", f"an item of {nbytes} bytes exceeds the {self._o['max_batch_bytes']}-byte request limit")
+            return
+        with self._lock:
+            self._queue.append(_Queued(item, nbytes, self._now()))
+            self._queue_bytes += nbytes
+            shed = self._shed_locked()
+            self._ensure_thread_locked()
+            if len(self._queue) >= self._o["flush_at"]:
+                self._wake.notify()
+        if shed:
+            self._drop_queue_full(shed)
+
+    def flush(self, timeout_s: Optional[float] = None) -> None:
+        """Send everything queued and wait for it, for at most ``timeout_s``."""
+        if self.mode == "immediate":
+            return
+        deadline = None if timeout_s is None else self._now() + timeout_s
+        with self._lock:
+            self._not_before = 0.0
+            self._flush_requested = True
+            self._ensure_thread_locked()
+            self._wake.notify_all()
+            while (self._queue or self._in_flight) and not self._stopped:
+                remaining = None if deadline is None else deadline - self._now()
+                if remaining is not None and remaining <= 0:
+                    break
+                self._wake.wait(timeout=min(0.1, remaining) if remaining is not None else 0.1)
+            self._flush_requested = False
+
+    def shutdown(self, timeout_s: Optional[float] = None) -> None:
+        self.flush(self._o["exit_flush_s"] if timeout_s is None else timeout_s)
+        with self._lock:
+            self._stopped = True
+            left = len(self._queue)
+            self._queue.clear()
+            self._queue_bytes = 0
+            self._wake.notify_all()
+        if left:
+            self._drop(left, "shutdown", f"{left} items were still queued at shutdown")
+
+    def stats(self) -> Dict[str, Any]:
+        with self._lock:
+            return {
+                "queued": len(self._queue), "queued_bytes": self._queue_bytes, "in_flight": self._in_flight,
+                "sent": self._stats["sent"], "dropped": self._stats["dropped"],
+                "dropped_by_reason": dict(self._stats["dropped_by_reason"]),
+                "paused_until": self._paused_until, "mode": self.mode,
+            }
+
+    # ── background thread ─────────────────────────────────────────────────────
+
+    def _ensure_thread_locked(self) -> None:
+        if self._thread is None or not self._thread.is_alive():
+            self._thread = threading.Thread(target=self._run, name="trodo-sender", daemon=True)
+            self._thread.start()
+
+    def _run(self) -> None:
+        interval = self._o["flush_interval_s"]
+        while True:
+            with self._lock:
+                while True:
+                    if self._stopped:
+                        return
+                    if not self._queue:
+                        self._wake.wait(timeout=interval)
+                        continue
+                    now = self._now()
+                    gate = max(self._paused_until or 0.0, self._not_before)
+                    if gate > now:
+                        self._wake.wait(timeout=gate - now)
+                        continue
+                    if self._flush_requested or len(self._queue) >= self._o["flush_at"]:
+                        break
+                    age = now - self._queue[0].enqueued_at
+                    if age >= interval:
+                        break
+                    self._wake.wait(timeout=interval - age)
+                batch = self._take_batch_locked()
+                self._in_flight += 1
+            try:
+                self._send_batch(batch)
+            finally:
+                with self._lock:
+                    self._in_flight -= 1
+                    self._wake.notify_all()
+
+    def _take_batch_locked(self) -> List[_Queued]:
+        out: List[_Queued] = []
+        nbytes = 0
+        while self._queue and len(out) < self._o["flush_at"]:
+            nxt = self._queue[0]
+            if out and nbytes + nxt.nbytes > self._o["max_batch_bytes"]:
+                break
+            out.append(self._queue.popleft())
+            nbytes += nxt.nbytes
+        self._queue_bytes -= nbytes
+        return out
+
+    def _send_batch(self, batch: List[_Queued]) -> None:
+        t = self._now()
+        for q in batch:
+            q.attempts += 1
+            if q.first_tried_at is None:
+                q.first_tried_at = t
+        try:
+            status, retry_after, body = self._http.post_raw(
+                endpoints.BATCH, self._envelope(batch), timeout=self._o["request_timeout_s"], gzip_body=True,
+            )
+        except Exception as exc:  # network error, timeout
+            self._log(f"batch of {len(batch)} failed: {exc}")
+            self._requeue(batch, None)
+            return
+        if status == 200 and isinstance(body, dict) and isinstance(body.get("results"), list):
+            self._reported()
+            self._settle(batch, body)
+            return
+        if status == 429:
+            self._pause(parse_retry_after_s(retry_after, self._now()))
+            self._requeue(batch, 0.0)
+            return
+        if status == 413:
+            self._split(batch)
+            return
+        if status in _TRANSIENT:
+            self._requeue(batch, None)
+            return
+        if status == 404:
+            self._legacy_send(batch)
+            return
+        self._drop(len(batch), "rejected", f"POST {endpoints.BATCH} -> HTTP {status}: {json.dumps(body)[:300]}")
+
+    def _settle(self, batch: List[_Queued], body: Dict[str, Any]) -> None:
+        keep: List[_Queued] = []
+        rejected = 0
+        first_error = None
+        results = body["results"]
+        for i, q in enumerate(batch):
+            r = results[i] if i < len(results) and isinstance(results[i], dict) else {"status": 500}
+            st = int(r.get("status", 500))
+            if 200 <= st < 300:
+                with self._lock:
+                    self._stats["sent"] += 1
+                continue
+            if st == 429 or st >= 500 or st == 408:
+                keep.append(q)
+                continue
+            if st == 413:
+                self._drop(1, "too_large", r.get("error") or "payload too large")
+                continue
+            rejected += 1
+            first_error = first_error or f"HTTP {st}: {r.get('error', '')}"
+        if rejected:
+            self._drop(rejected, "rejected", f"{rejected} item(s) rejected by the server ({first_error})")
+        ra = body.get("retry_after_ms")
+        if ra:
+            self._pause(float(ra) / 1000.0)
+        if keep:
+            self._requeue(keep, 0.0 if ra else None)
+
+    def _requeue(self, batch: List[_Queued], wait_s: Optional[float]) -> None:
+        t = self._now()
+        alive: List[_Queued] = []
+        for q in batch:
+            if q.first_tried_at is not None and t - q.first_tried_at > self._o["max_retry_s"]:
+                self._drop(1, "gave_up", f"an item was retried for {int(self._o['max_retry_s'])} s without being accepted")
+            else:
+                alive.append(q)
+        if not alive:
+            return
+        with self._lock:
+            for q in reversed(alive):
+                self._queue.appendleft(q)
+            self._queue_bytes += sum(q.nbytes for q in alive)
+            shed = self._shed_locked()
+            attempts = max(q.attempts for q in alive)
+            backoff = wait_s if wait_s is not None else min(_MAX_BACKOFF_S, _MIN_BACKOFF_S * 2 ** (attempts - 1)) * (0.5 + random.random() / 2)
+            self._not_before = t + backoff
+        if shed:
+            self._drop_queue_full(shed)
+
+    def _split(self, batch: List[_Queued]) -> None:
+        if len(batch) == 1:
+            self._drop(1, "too_large", f"an item of {batch[0].nbytes} bytes was refused as too large")
+            return
+        with self._lock:
+            for q in reversed(batch):
+                self._queue.appendleft(q)
+            self._queue_bytes += sum(q.nbytes for q in batch)
+            self._o["flush_at"] = max(1, len(batch) // 2)
+            self._wake.notify()
+
+    def _pause(self, secs: Optional[float]) -> None:
+        wait = min(secs if secs is not None else 30.0, self._o["max_retry_after_s"])
+        with self._lock:
+            self._paused_until = self._now() + wait
+        self._log(f"rate limited; paused for {int(wait)} s")
+
+    def _legacy_send(self, batch: List[_Queued]) -> None:
+        """A server before 2.24 has no /batch: each item goes to its own route,
+        one attempt, the status read — a refusal keeps the item like the batch
+        path would, instead of the old blocking request that dropped it."""
+        keep: List[_Queued] = []
+        wait: Optional[float] = None
+        for q in batch:
+            path, body = _legacy_route(q.item)
+            try:
+                status, retry_after, resp = self._http.post_raw(path, body, timeout=self._o["request_timeout_s"], gzip_body=True)
+            except Exception:
+                status, retry_after, resp = None, None, None
+            if status is not None and 200 <= status < 300:
+                with self._lock:
+                    self._stats["sent"] += 1
+                continue
+            if status is None or status in _TRANSIENT:
+                keep.append(q)
+                if status == 429:
+                    wait = parse_retry_after_s(retry_after, self._now()) or wait
+                continue
+            self._drop(1, "too_large" if status == 413 else "rejected", f"POST {path} -> HTTP {status}: {json.dumps(resp)[:200]}")
+        if wait is not None:
+            self._pause(wait)
+        if keep:
+            self._requeue(keep, 0.0 if wait is not None else None)
+
+    def _shed_locked(self) -> int:
+        """Drop the oldest until the queue fits; returns how many (the caller reports, outside the lock)."""
+        n = 0
+        while len(self._queue) > self._o["max_queue_items"] or self._queue_bytes > self._o["max_queue_bytes"]:
+            q = self._queue.popleft()
+            self._queue_bytes -= q.nbytes
+            n += 1
+        return n
+
+    def _drop_queue_full(self, n: int) -> None:
+        self._drop(n, "queue_full", f"the delivery queue is full ({self._o['max_queue_items']} items / {self._o['max_queue_bytes'] // 1048576} MB); the {n} oldest were dropped")
+
+    def _envelope(self, batch: List[_Queued]) -> Dict[str, Any]:
+        items = [q.item for q in batch]
+        with self._lock:
+            if not self._unreported["count"]:
+                return {"items": items}
+            return {"items": items, "dropped": {"count": self._unreported["count"], "by_reason": dict(self._unreported["by_reason"])}}
+
+    def _reported(self) -> None:
+        with self._lock:
+            self._unreported = {"count": 0, "by_reason": {}}
+
+    def _drop(self, n: int, reason: str, message: str) -> None:
+        with self._lock:
+            self._stats["dropped"] += n
+            self._stats["dropped_by_reason"][reason] = self._stats["dropped_by_reason"].get(reason, 0) + n
+            self._unreported["count"] += n
+            self._unreported["by_reason"][reason] = self._unreported["by_reason"].get(reason, 0) + n
+            warned = self._warned_drop
+            self._warned_drop = True
+        err = RuntimeError(f"trodo-python: {message}")
+        if self._on_error:
+            try:
+                self._on_error(err)
+            except Exception:
+                pass
+            return
+        if warned:
+            self._log(message)
+            return
+        sys.stderr.write(
+            f"[trodo-python] {message}\n"
+            "[trodo-python] Traces were dropped. Pass on_error to trodo.init(on_error=...) to handle these yourself; "
+            "further drops in this process stay quiet.\n"
+        )
+
+    # ── immediate ─────────────────────────────────────────────────────────────
+
+    def _send_immediate(self, item: Item) -> None:
+        deadline = self._now() + self._o["immediate_retry_s"]
+        attempt = 0
+        q = _Queued(item, 0, self._now())
+        while True:
+            attempt += 1
+            q.attempts = attempt
+            try:
+                status, retry_after, body = self._http.post_raw(
+                    endpoints.BATCH, self._envelope([q]),
+                    timeout=min(self._o["request_timeout_s"], max(1.0, deadline - self._now())), gzip_body=True,
+                )
+            except Exception:
+                status, retry_after, body = None, None, None
+            if status == 200 and isinstance(body, dict):
+                self._reported()
+                results = body.get("results") or []
+                r = results[0] if results and isinstance(results[0], dict) else {"status": 200}
+                st = int(r.get("status", 200))
+                if 200 <= st < 300:
+                    with self._lock:
+                        self._stats["sent"] += 1
+                    return
+                if not (st == 429 or st >= 500 or st == 408):
+                    self._drop(1, "too_large" if st == 413 else "rejected", f"HTTP {st}: {r.get('error', '')}")
+                    return
+            elif status == 404:
+                # No /batch on this server: the item's own route, within the same budget.
+                path, body = _legacy_route(item)
+                try:
+                    r_status, r_retry, _ = self._http.post_raw(path, body, timeout=min(self._o["request_timeout_s"], max(1.0, deadline - self._now())), gzip_body=True)
+                except Exception:
+                    r_status, r_retry = None, None
+                if r_status is not None and 200 <= r_status < 300:
+                    with self._lock:
+                        self._stats["sent"] += 1
+                    return
+                if r_status is not None and r_status not in _TRANSIENT:
+                    self._drop(1, "rejected", f"POST {path} -> HTTP {r_status}")
+                    return
+                status, retry_after = r_status, r_retry
+            elif status is not None and status not in _TRANSIENT:
+                self._drop(1, "rejected", f"POST {endpoints.BATCH} -> HTTP {status}")
+                return
+            if status == 429:
+                wait = parse_retry_after_s(retry_after, self._now()) or 2.0
+            else:
+                wait = _MIN_BACKOFF_S * 2 ** (attempt - 1)
+            wait = min(wait, deadline - self._now())
+            if wait <= 0:
+                self._drop(1, "gave_up", f"an item could not be delivered within {int(self._o['immediate_retry_s'])} s (immediate mode)")
+                return
+            self._sleep(wait)
+
+    def _atexit(self) -> None:
+        try:
+            self.flush(self._o["exit_flush_s"])
+        except Exception:
+            pass
+
+    def _log(self, msg: str) -> None:
+        if self._debug:
+            sys.stderr.write(f"[trodo-python] {msg}\n")
+
+
+def _legacy_route(item: Item):
+    """The pre-2.24 route and body for one item."""
+    if "run" in item:
+        return endpoints.RUNS_INGEST, item
+    if "feedback" in item:
+        return f"{endpoints.RUNS_BASE}/{item['run_id']}/feedback", item["feedback"]
+    if "run_id" in item:
+        return f"{endpoints.RUNS_BASE}/{item['run_id']}/spans", {"spans": item["spans"]}
+    return endpoints.SPANS_APPEND, {"spans": item["spans"]}
+
+
+def _size_of(item: Any) -> int:
+    try:
+        return len(json.dumps(item, default=str).encode("utf-8"))
+    except Exception:
+        return 0
+
+
+def gzip_json(body: Any) -> bytes:
+    return gzip.compress(json.dumps(body, default=str).encode("utf-8"))

trodo/otel/processor.py

@@ -107,8 +107,11 @@ class TrodoSpanProcessor:
         http_client: Any,
         flush_interval_s: float = 5.0,
         max_spans_per_run: int = 1000,
+        sender: Any = None,
     ) -> None:
         self._http = http_client
+        # The background sender (2.24). Without one, sends block as before 2.24.
+        self._sender = sender
         self._flush_interval = flush_interval_s
         self._max_spans = max_spans_per_run
         self._pending: Dict[str, List[TrodoSpan]] = {}
@@ -142,10 +145,16 @@ class TrodoSpanProcessor:
                 if len(bucket) < self._max_spans:
                     bucket.append(span)
         if joined:
-            try:
-                self._http.post_spans_append(span.run_id, [span.to_dict()])
-            except Exception:
-                pass
+            self._send_spans(span.run_id, [span.to_dict()])
+
+    def _send_spans(self, run_id: str, spans: List[Dict[str, Any]]) -> None:
+        if self._sender is not None:
+            self._sender.enqueue({"run_id": run_id, "spans": spans})
+            return
+        try:
+            self._http.post_spans_append(run_id, spans)
+        except Exception:
+            pass
 
     def get_pending(self, run_id: str) -> List[TrodoSpan]:
         with self._lock:
@@ -158,6 +167,10 @@ class TrodoSpanProcessor:
         payload: Dict[str, Any] = {"run": run.to_dict()}
         if spans:
             payload["spans"] = [s.to_dict() for s in spans]
+        if self._sender is not None:
+            # Queued: the agent's caller never waits on the network (2.24).
+            self._sender.enqueue(payload)
+            return
         try:
             self._http.post_run_ingest(payload)
         except Exception:
@@ -186,10 +199,7 @@ class TrodoSpanProcessor:
         """Stream spans for a long-running or joined run without finalising."""
         if not spans:
             return
-        try:
-            self._http.post_spans_append(run_id, [s.to_dict() for s in spans])
-        except Exception:
-            pass
+        self._send_spans(run_id, [s.to_dict() for s in spans])
 
     def force_flush(self) -> None:
         """Flush any buffered spans that don't have a run finalise yet."""
@@ -199,12 +209,7 @@ class TrodoSpanProcessor:
         for run_id, spans in pending:
             if not spans:
                 continue
-            try:
-                self._http.post_spans_append(
-                    run_id, [s.to_dict() for s in spans]
-                )
-            except Exception:
-                pass
+            self._send_spans(run_id, [s.to_dict() for s in spans])
 
     def shutdown(self) -> None:
         self._shutdown = True

trodo/otel/wrap_agent.py

@@ -611,6 +611,17 @@ class wrap_agent:
             return self._exit_otel(exc_type, exc, tb)
         return self._exit_trodo(exc_type, exc, tb)
 
+    # ``async with trodo.wrap_agent(...)`` (2.24). Entering and leaving a run
+    # is bookkeeping in this process — contextvars and a queue hand-off — so
+    # the async form is the sync one; the event loop is never blocked, because
+    # the send happens on the sender's thread (or, in immediate mode, is the
+    # one blocking call a serverless handler wants before it returns).
+    async def __aenter__(self) -> RunHandle:
+        return self.__enter__()
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        return self.__exit__(exc_type, exc, tb)
+
     # ----------------------------------------------------------------------
     # Legacy 'trodo' transport — TrodoSpanProcessor + Trodo HTTP API path.
     # ----------------------------------------------------------------------

{trodo_python-2.23.4.dist-info → trodo_python-2.24.0.dist-info}/METADATA

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

{trodo_python-2.23.4.dist-info → trodo_python-2.24.0.dist-info}/RECORD

@@ -1,14 +1,17 @@
-trodo/__init__.py,sha256=SbEfXeTk-1B_rMcbO2kCU66Ock4p7pmiEBLQGttMaP4,26928
-trodo/client.py,sha256=9UYaHZtWPMYdlG2xWVf77PQJ9DfFgN-zobTh60i8_Cc,22453
+trodo/__init__.py,sha256=ahX3Z2VcSDifpb6xg4RNUJzLe64Oka2TY2vNLey2f8M,27913
+trodo/_version.py,sha256=fSs1-zmlRM8V2BkYDf5P5v8U0xEG-QAN-jPcvTDYQLU,23
+trodo/client.py,sha256=6k6HeKrGV2720kK17--u6BjbhAUFZNUzpd9yEYiaQOs,24137
 trodo/types.py,sha256=eySgUvCXROG2TxtxgiU0MNr5iH0DEcduK8bmYtTKG44,3138
 trodo/user_context.py,sha256=uHCI2WYoOI3cNwdIUEuZdX4VYSu14pzm348ksn6hn_c,8195
 trodo/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/api/_retry.py,sha256=mHhuzfe3QuYa6j9BqRYVClvnYH0o3WkXXngmSwqWfgY,1214
 trodo/api/async_client.py,sha256=qF97NbvoYbNhem8uXtPh14EG4JVAhEAzUCYn7busaaA,3609
-trodo/api/endpoints.py,sha256=H0Da456mf2IUNZH5bsln69IIUoUhdF4bncPo-WDLZ9I,1433
-trodo/api/http_client.py,sha256=wzvxUpY2bR8BvebqbmqeHizVBmw41TmY3WQWVeAzABg,9881
+trodo/api/endpoints.py,sha256=SGgVELcVfwuCrRwlVPW2j0KYkaMtwLFPpdMtGtlqPeA,1574
+trodo/api/http_client.py,sha256=Vnw8l_QyoslCF2lJIxoH2uoUNFAK-8S_YfnWN8f4ZS0,11362
 trodo/auto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/auto/auto_event_manager.py,sha256=cztuRsRkNoJE5R4NfSfTrTJTGl4jx2Yb-Ncy0aVAPo8,4247
+trodo/delivery/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trodo/delivery/sender.py,sha256=urO7m6mRMnSEW7_cNAmJ4A6jtDNxuihZHOxCx1jQScI,21348
 trodo/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/managers/dataset_manager.py,sha256=gx0S8ujG3cbw4IskBNMdceBjDbcEh_nebwKSzEvm7hE,2827
 trodo/managers/experiment_manager.py,sha256=V-vemLtenfSI5VIcP0HPiXzEy8AyTrRrbJVCA9Z6wjo,10579
@@ -20,11 +23,11 @@ trodo/otel/__init__.py,sha256=yiRFXWUU45bAM2CV37XeO7zf1hmnmjufdP4XO50yEyE,624
 trodo/otel/auto_instrument.py,sha256=I_F3NCvc0JML2UpX9PaxFM3OGzMSuEYYfxZYTwkQDuo,26224
 trodo/otel/context.py,sha256=Jd0aTc0Q-1dM5kXXinhZD8YtnpdKgvneNiODyboVGKY,1418
 trodo/otel/helpers.py,sha256=XOMWcgZHaq5SQbkFxDaXPE4CDFjn01xjJmJ1vIxvwpw,20730
-trodo/otel/processor.py,sha256=LKlXxP3BeQ7DP8SzYAgXZZOeJ6-6b7e43i19gCUC_0Y,7939
+trodo/otel/processor.py,sha256=WgtLdXT9gpR4TZ_9iuoX-kBP4UN4nelCtoDnogtW_Qc,8289
 trodo/otel/prompt_trace.py,sha256=d2A6UhlWAgHZLIKtU0NxgGUpHk_z3F2Nm4u4QTAC3tA,7332
 trodo/otel/register.py,sha256=bV_ePTfUvPugig2GZnylhzxi2QfoPWs96A9mGLPMrSQ,9387
 trodo/otel/transport.py,sha256=hzZz8gwSMGJ8CxdijmLn1Ljt18owr9XTWy13DLbwYbw,2441
-trodo/otel/wrap_agent.py,sha256=PiluY8r_yvGtuST45sqYWDbtF0trmKFQRiN0vbZl8Rk,43948
+trodo/otel/wrap_agent.py,sha256=qx2jnuVIMZTv-PpRt-qFWqMWz1YO4jqY5pwgBQirVDo,44519
 trodo/prompts/__init__.py,sha256=yunNc8WkTSfEEkRR-NZWXAt_ZB3Ee2INRh-4RE7uHj4,806
 trodo/prompts/compile.py,sha256=XoKDKz6Yaofhrk-87AVW-SnwbiXLvfp161AL2bAFzNY,8802
 trodo/prompts/template.py,sha256=eGO2ZVNOw6JK7Ffj1UCYDMJFYyX5qQW2POlmFJSQpAo,9975
@@ -37,7 +40,7 @@ trodo/session/server_session.py,sha256=McsudEiq33XDq3nqxgzBcUvIjQxCMscwEuAPnYXrT
 trodo/session/session_manager.py,sha256=7ht5LeeZX1HLLfPeNV_a8NkXGbHl3up0CRtCGr3EzjQ,2995
 trodo/util/__init__.py,sha256=Z9c4rPPdKg06Kk3byKheDqksSgR4WNvS475oQ5sNljc,54
 trodo/util/lru.py,sha256=QIsM7s6J_E9ZjiXatSyReZIEeGypTAcgrPWWy8YsRa4,2465
-trodo_python-2.23.4.dist-info/METADATA,sha256=VQP23ftatdvKhd55L_qv-XX60zq7OuTjVKI0c6Kw9dI,25308
-trodo_python-2.23.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-trodo_python-2.23.4.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
-trodo_python-2.23.4.dist-info/RECORD,,
+trodo_python-2.24.0.dist-info/METADATA,sha256=zDBPYuJWTElYQQgr1S8qeDzl1chRfwbNtESdc-PFe1M,25308
+trodo_python-2.24.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+trodo_python-2.24.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-2.24.0.dist-info/RECORD,,