cmpnd 0.85.0__tar.gz → 0.85.1__tar.gz

{cmpnd-0.85.0 → cmpnd-0.85.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.85.0
+Version: 0.85.1
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.85.0 → cmpnd-0.85.1}/docs/sdk-instrumentation.md

@@ -331,6 +331,18 @@ Each `_send_*` method routes a failed delivery to one of two counters: a `429` (
 
 Tolerating is never silent. A send that recovered logs a warning naming what it rode through (`rode through 3 transient responses over 12.4s (503=3) to POST /api/v1/traces`), and an exhausted budget raises `ExportRetriesExhausted` with the same count and window in its message. `BatchExporter.failure_summary()` reports the distribution of non-2xx statuses observed, how many transient answers were ridden through, and a sample error body — that's what the stress lane prints when it fails, so a red lane says *what* the wire answered rather than only how many errors there were.
 
+Trace delivery failures log at ERROR on `cmpnd.exporter`. The message names the
+operation and the number of records the exporter will not resend. HTTP failures
+include the status, route and serve's string `error`, `error_code`, `upgrade` and
+`field` values when present. The exporter bounds each value and escapes control
+characters. It omits other body fields and non-JSON responses. Exhausted retries
+include the last server message as well as the attempt count and elapsed time.
+
+A non-retryable 422 discards the submission. Upgrade the SDK when serve asks for
+it, then emit fresh telemetry. An upgrade cannot recover discarded records.
+Background failures keep the application running and increment the existing
+error counters. They do not raise an exception in the instrumented program.
+
 ### The retryable-error contract
 
 The server tells a client when a failed write is worth re-sending, in three signals carrying one fact:

{cmpnd-0.85.0 → cmpnd-0.85.1}/ingest/cmpnd_ingest/exporter_http.py

@@ -59,6 +59,31 @@ logger = logging.getLogger("cmpnd.exporter")
 _GZIP_HEADERS = {"Content-Encoding": "gzip"}
 
 
+def _export_error_detail(exc: Exception) -> str:
+    """Keep delivery errors useful in background logs without dumping response bodies."""
+
+    def text(value: str, limit: int = 300) -> str:
+        return json.dumps(value[:limit], ensure_ascii=True)[1:-1]
+
+    cause = exc.__cause__ if isinstance(exc, ExportRetriesExhausted) else exc
+    if not isinstance(cause, httpx.HTTPStatusError):
+        return text(str(exc), 600)
+    response = cause.response
+    detail = f"HTTP {response.status_code} for {cause.request.method} {cause.request.url.path}"
+    if cause is not exc:
+        detail = f"{text(str(exc), 600)}; {detail}"
+    try:
+        body = response.json()
+    except (ValueError, httpx.ResponseNotRead):
+        return detail
+    if isinstance(body, dict):
+        for key in ("error", "error_code", "upgrade", "field"):
+            value = body.get(key)
+            if isinstance(value, str) and value:
+                detail += f"; {key}={text(value)}"
+    return detail
+
+
 def _send_json(client: httpx.Client, method: str, path: str, payload: Any) -> httpx.Response:
     """POST/PATCH/PUT ``payload`` as gzipped JSON.
 
@@ -1581,15 +1606,30 @@ class BatchExporter:
                 # drop call for opposite responses from the caller.
                 self._record_drop("trace", "server_shed", count=len(traces_to_send), log=False)
             else:
-                logger.error(f"Failed to export traces batch: {e}")
+                logger.error(
+                    "Failed to export traces batch. Records will not be resent (count=%s, traces=%s, spans=%s): %s",
+                    len(traces_to_send) + total_spans,
+                    len(traces_to_send),
+                    total_spans,
+                    _export_error_detail(e),
+                )
                 with self._stats_lock:
                     self._error_count += len(traces_to_send)
         except Exception as e:
-            logger.error(f"Failed to export traces batch: {e}")
+            logger.error(
+                "Failed to export traces batch. Records will not be resent (count=%s, traces=%s, spans=%s): %s",
+                len(traces_to_send) + total_spans,
+                len(traces_to_send),
+                total_spans,
+                _export_error_detail(e),
+            )
             with self._stats_lock:
                 self._error_count += len(traces_to_send)
 
     def _send_encoded_trace(self, trace: EncodedTraceBody) -> None:
+        # The body stays compressed end to end, so the exporter never learns how
+        # many spans it embeds. A failure names the one trace and says the span
+        # count is unknown, rather than understating the loss as one record.
         client = self._require_client()
         try:
             self._send_retrying(
@@ -1601,11 +1641,19 @@ class BatchExporter:
             if e.response.status_code == 429:
                 self._record_drop("trace", "server_shed", count=1)
             else:
-                logger.error(f"Failed to export encoded trace {trace.trace_id}: {e}")
+                logger.error(
+                    "Failed to export encoded trace %s. Records will not be resent (traces=1, spans=unknown): %s",
+                    trace.trace_id,
+                    _export_error_detail(e),
+                )
                 with self._stats_lock:
                     self._error_count += 1
         except Exception as e:
-            logger.error(f"Failed to export encoded trace {trace.trace_id}: {e}")
+            logger.error(
+                "Failed to export encoded trace %s. Records will not be resent (traces=1, spans=unknown): %s",
+                trace.trace_id,
+                _export_error_detail(e),
+            )
             with self._stats_lock:
                 self._error_count += 1
 
@@ -1619,7 +1667,11 @@ class BatchExporter:
                     self._exported_count += 1
                 logger.debug(f"Started trace {trace_id}")
             except Exception as e:
-                logger.error(f"Failed to start trace {trace_id}: {e}")
+                logger.error(
+                    "Failed to start trace %s. Records will not be resent (count=1): %s",
+                    trace_id,
+                    _export_error_detail(e),
+                )
                 with self._stats_lock:
                     self._error_count += 1
 
@@ -1651,7 +1703,12 @@ class BatchExporter:
                 self._exported_count += len(span_list)
             logger.debug(f"Exported {len(span_list)} spans for trace {trace_id}")
         except Exception as e:
-            logger.error(f"Failed to export spans for trace {trace_id}: {e}")
+            logger.error(
+                "Failed to export spans for trace %s. Records will not be resent (count=%s): %s",
+                trace_id,
+                len(span_list),
+                _export_error_detail(e),
+            )
             with self._stats_lock:
                 self._error_count += len(span_list)
 
@@ -1667,7 +1724,11 @@ class BatchExporter:
                     self._exported_count += 1
                 logger.debug(f"Finalized trace {trace_id}")
             except Exception as e:
-                logger.error(f"Failed to finalize trace {trace_id}: {e}")
+                logger.error(
+                    "Failed to finalize trace %s. Records will not be resent (count=1): %s",
+                    trace_id,
+                    _export_error_detail(e),
+                )
                 with self._stats_lock:
                     self._error_count += 1
 

{cmpnd-0.85.0 → cmpnd-0.85.1}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.85.0"
+version = "0.85.1"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.85.0 → cmpnd-0.85.1}/scripts/seed_review_run.py

@@ -46,11 +46,15 @@ import logging
 import os
 import pathlib
 import re
+import sys
 import urllib.error
 import urllib.parse
 import urllib.request
 import uuid
 
+# The captured fixtures already depend on this repository's serve scripts.
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2] / "serve" / "scripts" / "seed_fixtures"))
+
 logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
 log = logging.getLogger("seed_review_run")
 
@@ -673,6 +677,14 @@ def _ensure_program(endpoint: str, api_key: str, name: str) -> str | None:
 
 
 def _post(endpoint: str, path: str, payload, api_key: str, method: str = "POST"):
+    if path.startswith("/api/v1/traces"):
+        from submission import prepare_trace_submission
+
+    if path == "/api/v1/traces/batch":
+        for trace in payload:
+            prepare_trace_submission(trace)
+    elif path.startswith("/api/v1/traces/") and path.endswith("/spans"):
+        prepare_trace_submission(payload, path.split("/")[-2])
     body = json.dumps(payload).encode("utf-8")
     req = urllib.request.Request(
         endpoint + path,
@@ -680,9 +692,13 @@ def _post(endpoint: str, path: str, payload, api_key: str, method: str = "POST")
         method=method,
         headers={"Content-Type": "application/json", "X-API-Key": api_key},
     )
-    with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310 - fixed https endpoint from env
-        raw = resp.read()
-        return resp.status, (json.loads(raw) if raw else {})
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310 - fixed https endpoint from env
+            raw = resp.read()
+            return resp.status, (json.loads(raw) if raw else {})
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "replace")[:400]
+        raise RuntimeError(f"{method} {path} returned HTTP {exc.code}: {detail!r}") from exc
 
 
 def _reserve_optimization(endpoint: str, api_key: str) -> str | None:

{cmpnd-0.85.0 → cmpnd-0.85.1}/tests/e2e/test_project_attribution.py

@@ -10,13 +10,11 @@ block so subsequent tests in the same pytest invocation are not affected.
 
 from __future__ import annotations
 
-import datetime
 import uuid
 from collections.abc import Callable
 from typing import Any
 
 import dspy
-import httpx
 import pytest
 
 import cmpnd
@@ -121,77 +119,6 @@ def test_project_stamped_on_trace_and_spans(server_client, trace_capture):
         _restore_session_config()
 
 
-def test_streaming_spans_inherit_full_project_tags(server_client):
-    """Spans added via the streaming path (POST /traces/:id/spans) inherit all
-    project_tags from the parent trace, not just the first tag.
-
-    This bypasses the SDK exporter and calls the API directly to simulate
-    an old SDK that sends project but not project_tags on spans. Serve must
-    preserve both tags from the parent trace.
-    """
-    trace_id = str(uuid.uuid4())
-    tag_a = f"e2e-stream-a-{uuid.uuid4().hex[:8]}"
-    tag_b = f"e2e-stream-b-{uuid.uuid4().hex[:8]}"
-    now = datetime.datetime.now(datetime.timezone.utc).isoformat()
-    headers = {
-        "X-API-Key": CMPND_E2E_API_KEY or "",
-        "Content-Type": "application/json",
-    }
-
-    # 1. Start trace with two tags
-    start_resp = httpx.post(
-        f"{E2E_ENDPOINT}/api/v1/traces/{trace_id}/start",
-        headers=headers,
-        json={
-            "module_class": "StreamTest",
-            "start_time": now,
-            "project": tag_a,
-            "project_tags": [tag_a, tag_b],
-        },
-        timeout=30.0,
-    )
-    assert start_resp.status_code == 202, f"start_trace failed: {start_resp.status_code} {start_resp.text}"
-
-    # 2. Add a span WITHOUT project_tags — simulates old SDK behavior
-    span_id = str(uuid.uuid4())
-    spans_resp = httpx.post(
-        f"{E2E_ENDPOINT}/api/v1/traces/{trace_id}/spans",
-        headers=headers,
-        json={
-            "spans": [
-                {
-                    "span_id": span_id,
-                    "trace_id": trace_id,
-                    "name": "predict",
-                    "span_type": "predict",
-                    "start_time": now,
-                    "end_time": now,
-                    # project and project_tags intentionally omitted
-                }
-            ]
-        },
-        timeout=30.0,
-    )
-    assert spans_resp.status_code == 200, f"add_spans failed: {spans_resp.status_code} {spans_resp.text}"
-
-    # 3. Poll for ingestion, then fetch the trace. The trace row and its spans
-    # become visible independently and asynchronously. Read the endpoint
-    # directly to keep the wait bounded by one retry loop (CMP-843).
-    def _spans():
-        resp = server_client._client.get(f"/api/v1/traces/{trace_id}")
-        return resp.json().get("spans", []) if resp.status_code == 200 else []
-
-    spans = poll_until(_spans, timeout=60.0, interval=3.0)
-
-    assert spans, "trace has no spans after streaming add"
-    for span in spans:
-        span_tags = span.get("project_tags", [])
-        assert tag_a in span_tags and tag_b in span_tags, (
-            f"span {span.get('span_id')} should inherit both tags from trace, "
-            f"got {span_tags!r} — expected {[tag_a, tag_b]!r}"
-        )
-
-
 def test_project_null_when_unset(server_client, trace_capture):
     """Without configure(project=...), the trace and spans land with NULL project."""
     try:

{cmpnd-0.85.0 → cmpnd-0.85.1}/tests/e2e/test_traces_read.py

@@ -29,7 +29,9 @@ class TestTracesReadE2E:
         trace_id = trace_capture.last_trace_id
         assert trace_id is not None, "no trace captured"
 
-        # Detail reads the ingested source without waiting for collection projection.
+        # Trace headers and spans publish independently. Wait until both are visible
+        # before checking the SDK's detail read.
+        server_client.get_trace(trace_id)
         detail = cmpnd.traces.show(trace_id, api_key=CMPND_E2E_API_KEY, endpoint=E2E_ENDPOINT)
         assert detail["trace"]["trace_id"] == trace_id
         assert isinstance(detail["spans"], list)

{cmpnd-0.85.0 → cmpnd-0.85.1}/tests/real_models/test_trace_search.py

@@ -78,8 +78,11 @@ def test_cross_trace_q_search_finds_the_span_token():
 
     # One trace, one span whose name carries the unique token. The write path
     # indexes that name in the span transaction, and the read below waits for
-    # the projected search collection to publish it.
+    # the projected search collection to publish it. Both records are
+    # self-contained submissions: each declares its schema version, and the span
+    # carries its own tags rather than inheriting the trace's.
     trace = {
+        "schema_version": 1,
         "trace_id": trace_id,
         "start_time": _iso(),
         "end_time": _iso(),
@@ -89,8 +92,11 @@ def test_cross_trace_q_search_finds_the_span_token():
         "span_count": 1,
         "spans": [
             {
+                "schema_version": 1,
                 "span_id": span_id,
                 "trace_id": trace_id,
+                "project_tags": [tag],
+                "tags": {},
                 "name": token,
                 "span_type": "tool",
                 "start_time": _iso(),

{cmpnd-0.85.0 → cmpnd-0.85.1}/tests/test_exporter.py

@@ -14,6 +14,7 @@ from uuid import uuid4
 
 import httpx
 import pytest
+from cmpnd_ingest.bodies import EncodedTraceBody
 
 from cmpnd import retry
 from cmpnd.configuration import Config
@@ -1179,3 +1180,125 @@ def test_failure_summary_is_quiet_when_nothing_failed():
     exporter._flush_batch([ExportItem(item_type="trace", data=_make_trace(), timestamp=0.0)])
 
     assert "no non-2xx" in exporter.failure_summary()
+
+
+@pytest.mark.parametrize(
+    "kind,count",
+    [("trace", 1), ("trace", 2), ("trace_start", 1), ("span", 2), ("trace_finalize", 1), ("encoded_trace", 1)],
+)
+def test_trace_rejection_logs_server_guidance_and_delivery_loss(kind, count, caplog):
+    body = {
+        "error": "schema_version must be 1",
+        "error_code": "trace_submission_contract",
+        "field": "schema_version",
+        "upgrade": "Upgrade with uv add cmpnd --upgrade",
+        "retryable": False,
+        "unrelated": "private response detail",
+    }
+    capture = ContractCapture([(422, body, {})])
+    exporter = _make_seq_exporter(capture)
+    tid = uuid4()
+    batch = []
+    for _ in range(count):
+        data = (
+            _make_span(trace_id=tid)
+            if kind == "span"
+            else EncodedTraceBody(str(tid), "gzip", gzip.compress(b"{}"))
+            if kind == "encoded_trace"
+            else _make_trace()
+        )
+        batch.append(ExportItem(item_type=kind, data=data, timestamp=0.0))
+    try:
+        with caplog.at_level(logging.ERROR, logger="cmpnd.exporter"):
+            exporter._flush_batch(batch)
+        assert len(capture.requests) == 1
+        assert exporter._error_count == count
+        assert exporter._exported_count == 0
+        assert "422" in caplog.text
+        assert "schema_version must be 1" in caplog.text
+        assert "trace_submission_contract" in caplog.text
+        assert "Upgrade with uv add cmpnd --upgrade" in caplog.text
+        if kind == "encoded_trace":
+            # The exporter never inflates an encoded trace, so it cannot count the
+            # spans the trace embeds and must not report the trace as one record.
+            assert "traces=1, spans=unknown" in caplog.text
+            assert "count=" not in caplog.text
+        else:
+            assert f"count={count}" in caplog.text
+        assert "Records will not be resent" in caplog.text
+        assert "private response detail" not in caplog.text
+    finally:
+        exporter.shutdown()
+
+
+@pytest.mark.parametrize(
+    "body", [[], {"error": {"secret": "private response detail"}}, {"error": "bad\nforged log\r\x1b[31m" + "x" * 5000}]
+)
+def test_trace_rejection_handles_unexpected_or_long_error_bodies(body, caplog):
+    requests = []
+
+    def handle(request):
+        requests.append(request)
+        return httpx.Response(400, json=body)
+
+    exporter = _make_exporter(RequestCapture())
+    exporter._client = httpx.Client(base_url=_make_config().endpoint, transport=httpx.MockTransport(handle))
+    try:
+        with caplog.at_level(logging.ERROR, logger="cmpnd.exporter"):
+            exporter._flush_batch([ExportItem(item_type="trace", data=_make_trace(), timestamp=0.0)])
+        messages = [r.getMessage() for r in caplog.records if r.levelno == logging.ERROR]
+        assert len(requests) == 1
+        assert len(messages) == 1
+        assert "400" in messages[0]
+        assert "count=1" in messages[0]
+        assert len(messages[0]) < 2000
+        assert "private response detail" not in messages[0]
+        assert "\nforged log" not in messages[0]
+        assert "\x1b" not in messages[0]
+    finally:
+        exporter.shutdown()
+
+
+def test_trace_rejection_handles_non_json_response(caplog):
+    exporter = _make_exporter(RequestCapture())
+    exporter._client = httpx.Client(
+        base_url=_make_config().endpoint,
+        transport=httpx.MockTransport(lambda _: httpx.Response(413, text="<html>private response detail</html>")),
+    )
+    try:
+        with caplog.at_level(logging.ERROR, logger="cmpnd.exporter"):
+            exporter._flush_batch([ExportItem(item_type="trace", data=_make_trace(), timestamp=0.0)])
+        assert "413" in caplog.text
+        assert "count=1" in caplog.text
+        assert "private response detail" not in caplog.text
+    finally:
+        exporter.shutdown()
+
+
+def test_retry_exhaustion_logs_last_server_message(caplog):
+    capture = ContractCapture([(503, {"error": "database temporarily unavailable", "retryable": True}, {})])
+    exporter = _make_seq_exporter(capture)
+    try:
+        with caplog.at_level(logging.ERROR, logger="cmpnd.exporter"):
+            exporter._flush_batch([ExportItem(item_type="trace", data=_make_trace(), timestamp=0.0)])
+        assert len(capture.requests) == retry.MAX_ATTEMPTS
+        assert "database temporarily unavailable" in caplog.text
+        assert "transient responses over" in caplog.text
+        assert "count=1" in caplog.text
+    finally:
+        exporter.shutdown()
+
+
+def test_rejected_full_trace_logs_embedded_span_loss(caplog):
+    capture = ContractCapture([(422, {"error": "invalid span", "retryable": False}, {})])
+    exporter = _make_seq_exporter(capture)
+    payload = _make_trace().to_api_dict()
+    payload["spans"] = [_make_span().to_api_dict(), _make_span().to_api_dict()]
+    try:
+        with caplog.at_level(logging.ERROR, logger="cmpnd.exporter"):
+            exporter._send_traces([payload])
+        assert "count=3, traces=1, spans=2" in caplog.text
+        assert exporter._exported_count == 0
+        assert len(capture.requests) == 1
+    finally:
+        exporter.shutdown()

{cmpnd-0.85.0 → cmpnd-0.85.1}/uv.lock

@@ -505,7 +505,7 @@ wheels = [
 
 [[package]]
 name = "cmpnd"
-version = "0.85.0"
+version = "0.85.1"
 source = { editable = "." }
 default-groups = ["dspy-3-4-1"]
 dependencies = [