spanlight 0.2.0__tar.gz → 0.2.1__tar.gz

{spanlight-0.2.0 → spanlight-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spanlight
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python SDK for Spanlight, open-source observability for LLM applications.
 Author: Dheeraj
 License-Expression: MIT

{spanlight-0.2.0 → spanlight-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spanlight"
-version = "0.2.0"
+version = "0.2.1"
 description = "Python SDK for Spanlight, open-source observability for LLM applications."
 readme = "README.md"
 license = "MIT"

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/_decorator.py

@@ -16,6 +16,7 @@ SDK itself are swallowed so they cannot break the decorated function.
 
 from __future__ import annotations
 
+import asyncio
 import functools
 import inspect
 import logging
@@ -252,6 +253,10 @@ async def _traced_async_generator(
     """Async counterpart of :func:`_traced_generator`."""
     collected = _OutputCollector(enabled=options.capture_output)
     step: Callable[[], Any] = functools.partial(generator.asend, None)
+    # A cancellation thrown in at a `yield` means the consumer abandoned the generator: asyncio
+    # closes one left behind by `async for ... break` that way at loop shutdown. Like a `break`
+    # over a sync generator, that ends the span as ok, not failed.
+    abandoned: BaseException | None = None
     while True:
         previous = get_current_span()
         token = set_current_span(span)
@@ -266,7 +271,15 @@ async def _traced_async_generator(
             )
             return
         except BaseException as exc:
-            _finish(span, error=exc)
+            if exc is abandoned:
+                _finish(
+                    span,
+                    output=collected.result(None),
+                    capture_output=options.capture_output,
+                    output_cut=collected.truncated,
+                )
+            else:
+                _finish(span, error=exc)
             raise
         finally:
             restore_current_span(token, previous)
@@ -286,6 +299,7 @@ async def _traced_async_generator(
                 )
             raise
         except BaseException as exc:
+            abandoned = exc if isinstance(exc, asyncio.CancelledError) else None
             step = functools.partial(generator.athrow, exc)
         else:
             step = functools.partial(generator.asend, sent)

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/_exporter.py

@@ -189,6 +189,8 @@ class BatchExporter:
             ``True`` if the queue drained in time, ``False`` otherwise.
         """
         try:
+            # A forked child must not wait on the parent's in-flight batch.
+            self._check_fork()
             self._ensure_worker()
             deadline = None if timeout is None else time.monotonic() + timeout
             with self._condition:

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/_exporter_delivery.py

@@ -135,12 +135,13 @@ class Delivery:
     def _send_batch(
         self, target: _Target, batch: list[SpanPayload], client: Mapping[str, Any] | None
     ) -> None:
+        batch, encoded = self._encode_each(target, batch)
         if not batch:
             return
-        envelope: dict[str, Any] = {target.body_key: batch}
+        fields = [f'"{target.body_key}":[{",".join(encoded)}]']
         if client is not None and target.body_key == SPANS:
-            envelope["client"] = dict(client)
-        body = json.dumps(envelope, separators=(",", ":"), default=str).encode()
+            fields.append('"client":' + json.dumps(dict(client), separators=(",", ":")))
+        body = ("{" + ",".join(fields) + "}").encode()
         if self._gzip:
             body = gzip.compress(body)
 
@@ -179,6 +180,27 @@ class Delivery:
             logger.debug("Export failed (%s); retrying in %.2fs", failure, delay)
             self._sleep(delay)
 
+    def _encode_each(
+        self, target: _Target, batch: list[SpanPayload]
+    ) -> tuple[list[SpanPayload], list[str]]:
+        """JSON-encode each item on its own, so one that cannot be encoded loses only itself."""
+        kept: list[SpanPayload] = []
+        encoded: list[str] = []
+        for item in batch:
+            try:
+                encoded.append(json.dumps(item, separators=(",", ":"), default=str))
+            except Exception as exc:
+                self.failed += 1
+                logger.warning(
+                    "Dropping %s %s: it cannot be encoded as JSON (%s)",
+                    target.body_key[:-1],
+                    item.get(target.id_field),
+                    type(exc).__name__,
+                )
+            else:
+                kept.append(item)
+        return kept, encoded
+
     def _split_and_send(
         self, target: _Target, batch: list[SpanPayload], client: Mapping[str, Any] | None
     ) -> None:

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/_serialize.py

@@ -18,7 +18,10 @@ from collections.abc import Mapping
 from typing import Any
 
 MAX_DEPTH = 12
-MAX_STRING_LENGTH = 32_000
+# Input and output strings: long enough that the server's 1 MiB payload cap is the one that
+# applies. Attribute strings stay short: the server refuses a span whose attributes pass 64 KB.
+MAX_STRING_LENGTH = 1_000_000
+MAX_ATTRIBUTE_STRING_LENGTH = 32_000
 MAX_ITEMS = 1_000
 
 _TRUNCATION_MARKER = "...[truncated]"
@@ -27,30 +30,41 @@ JsonValue = Any
 """Alias documenting that a value is JSON-compatible (recursive types are awkward)."""
 
 
-def to_jsonable(value: Any) -> JsonValue:
+def to_jsonable(value: Any, *, max_string: int = MAX_STRING_LENGTH) -> JsonValue:
     """Convert ``value`` into a JSON-compatible structure.
 
     Args:
         value: Any Python object.
+        max_string: The longest string kept whole, in characters.
 
     Returns:
         A value composed only of ``dict``, ``list``, ``str``, ``int``,
         ``float``, ``bool`` and ``None``. Unknown objects are rendered with
         ``repr``. Oversized strings and collections are truncated.
     """
-    return to_jsonable_cut(value)[0]
+    return to_jsonable_cut(value, max_string=max_string)[0]
 
 
-def to_jsonable_cut(value: Any) -> tuple[JsonValue, bool]:
+def to_jsonable_cut(value: Any, *, max_string: int = MAX_STRING_LENGTH) -> tuple[JsonValue, bool]:
     """Like :func:`to_jsonable`, plus whether anything was cut to fit the bounds."""
-    cut: list[bool] = []
+    cut = _Cut(max_string)
     try:
-        return _convert(value, 0, cut), bool(cut)
+        return _convert(value, 0, cut), cut.happened
     except Exception:
-        return _truncate_string(_safe_repr(value), cut), bool(cut)
+        return _truncate_string(_safe_repr(value), cut), cut.happened
 
 
-def _convert(value: Any, depth: int, cut: list[bool]) -> JsonValue:
+class _Cut:
+    """The string bound of one conversion, and whether anything was cut to fit the bounds."""
+
+    __slots__ = ("happened", "max_string")
+
+    def __init__(self, max_string: int) -> None:
+        self.max_string = max_string
+        self.happened = False
+
+
+def _convert(value: Any, depth: int, cut: _Cut) -> JsonValue:
     if value is None or isinstance(value, bool | int):
         return value
     if isinstance(value, float):
@@ -58,7 +72,7 @@ def _convert(value: Any, depth: int, cut: list[bool]) -> JsonValue:
     if isinstance(value, str):
         return _truncate_string(value, cut)
     if depth >= MAX_DEPTH:
-        cut.append(True)
+        cut.happened = True
         return "[max depth reached]"
 
     if isinstance(value, Mapping):
@@ -86,22 +100,22 @@ def _convert(value: Any, depth: int, cut: list[bool]) -> JsonValue:
     return _truncate_string(_safe_repr(value), cut)
 
 
-def _convert_mapping(value: Mapping[Any, Any], depth: int, cut: list[bool]) -> dict[str, JsonValue]:
+def _convert_mapping(value: Mapping[Any, Any], depth: int, cut: _Cut) -> dict[str, JsonValue]:
     result: dict[str, JsonValue] = {}
     for index, (key, item) in enumerate(value.items()):
         if index >= MAX_ITEMS:
             result["..."] = f"{len(value) - MAX_ITEMS} more keys truncated"
-            cut.append(True)
+            cut.happened = True
             break
         result[str(key)] = _convert(item, depth + 1, cut)
     return result
 
 
-def _convert_sequence(items: list[Any], depth: int, cut: list[bool]) -> list[JsonValue]:
+def _convert_sequence(items: list[Any], depth: int, cut: _Cut) -> list[JsonValue]:
     converted = [_convert(item, depth + 1, cut) for item in items[:MAX_ITEMS]]
     if len(items) > MAX_ITEMS:
         converted.append(f"... {len(items) - MAX_ITEMS} more items truncated")
-        cut.append(True)
+        cut.happened = True
     return converted
 
 
@@ -122,11 +136,11 @@ def _dump_model(value: Any) -> Any | None:
     return None
 
 
-def _truncate_string(value: str, cut: list[bool]) -> str:
-    if len(value) <= MAX_STRING_LENGTH:
+def _truncate_string(value: str, cut: _Cut) -> str:
+    if len(value) <= cut.max_string:
         return value
-    cut.append(True)
-    return value[:MAX_STRING_LENGTH] + _TRUNCATION_MARKER
+    cut.happened = True
+    return value[: cut.max_string] + _TRUNCATION_MARKER
 
 
 def _safe_repr(value: Any) -> str:

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/_span.py

@@ -18,7 +18,7 @@ from collections.abc import Callable, Mapping
 from typing import Any, Literal, get_args
 
 from ._ids import new_span_id
-from ._serialize import JsonValue, to_jsonable, to_jsonable_cut
+from ._serialize import MAX_ATTRIBUTE_STRING_LENGTH, JsonValue, to_jsonable_cut
 from ._trace_state import TraceState
 from ._usage import SpanUsage
 
@@ -91,9 +91,11 @@ class Span(SpanUsage):
         self.prompt_version_id: str | None = None
         self.input: JsonValue = None
         self.output: JsonValue = None
-        # Whether the SDK cut the input or output to fit its bounds; sent as `truncated`.
+        # Whether the SDK cut the input, output or an attribute to fit its bounds; sent as
+        # `truncated`.
         self._input_cut = False
         self._output_cut = False
+        self._attributes_cut = False
         self.attributes: dict[str, JsonValue] = {}
 
         self._on_end = on_end
@@ -128,12 +130,24 @@ class Span(SpanUsage):
 
     def set_attribute(self, key: str, value: Any) -> None:
         """Attach a single custom attribute."""
-        if self._mutable:
-            self.attributes[str(key)] = to_jsonable(value)
+        if not self._mutable:
+            return
+        try:
+            converted, cut = to_jsonable_cut(value, max_string=MAX_ATTRIBUTE_STRING_LENGTH)
+            self.attributes[str(key)] = converted
+        except Exception:
+            logger.debug("Ignoring an attribute whose key cannot be turned into text")
+            return
+        self._attributes_cut = self._attributes_cut or cut
 
     def set_attributes(self, attributes: Mapping[str, Any]) -> None:
         """Attach several custom attributes at once."""
-        for key, value in attributes.items():
+        try:
+            items = dict(attributes).items()
+        except Exception:
+            logger.debug("set_attributes() needs a mapping, got %s", type(attributes).__name__)
+            return
+        for key, value in items:
             self.set_attribute(key, value)
 
     def set_model(self, model: str | None, *, provider: str | None = None) -> None:
@@ -186,7 +200,7 @@ class Span(SpanUsage):
             elapsed_ns = time.perf_counter_ns() - self._start_perf_ns
             self.time_to_first_token_ms = elapsed_ns / 1_000_000
 
-    def record_error(self, error: BaseException | str) -> None:
+    def record_error(self, error: BaseException | str | None) -> None:
         """Mark the span as failed.
 
         Args:
@@ -195,12 +209,17 @@ class Span(SpanUsage):
         if not self._mutable:
             return
         self.status = "error"
-        if isinstance(error, BaseException):
-            message = str(error) or type(error).__name__
-            self.attributes["error.type"] = type(error).__name__
-        else:
-            message = error
-        self.status_message = message[:_MAX_STATUS_MESSAGE]
+        message: str | None = None
+        try:
+            if isinstance(error, BaseException):
+                self.attributes["error.type"] = type(error).__name__
+                message = str(error) or type(error).__name__
+            elif error is not None:
+                message = str(error)
+        except Exception:
+            # The exception's own `__str__` raised; its type is still a useful message.
+            message = type(error).__name__
+        self.status_message = message[:_MAX_STATUS_MESSAGE] if message else None
 
     def end(self) -> None:
         """Finish the span and hand it to the exporter. Idempotent."""
@@ -244,7 +263,7 @@ class Span(SpanUsage):
         # Sent only when set, so payloads for servers that predate prompts stay unchanged.
         if self.prompt_version_id is not None:
             payload["prompt_version_id"] = self.prompt_version_id
-        if self._input_cut or self._output_cut:
+        if self._input_cut or self._output_cut or self._attributes_cut:
             payload["truncated"] = True
         return payload
 

spanlight-0.2.1/src/spanlight/_trace_state.py

@@ -0,0 +1,131 @@
+"""Trace-level state shared by every span of one trace.
+
+The server rejects every span of a trace whose trace-level fields break its limits, so the
+SDK makes them fit instead: ``""`` means unset, a non-string becomes its text, text is cut to
+the limit (name, user and session ids 256 characters, environment 64, release 128) and a trace
+keeps at most 20 tags of up to 64 characters. Each kind of fix is logged once per process.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Iterable, Mapping
+
+from ._ids import new_trace_id
+from ._metadata import clean_metadata, merge_metadata
+from ._serialize import JsonValue
+
+logger = logging.getLogger("spanlight")
+
+MAX_TEXT = 256
+MAX_ENVIRONMENT = 64
+MAX_RELEASE = 128
+MAX_TAGS = 20
+MAX_TAG = 64
+
+_logged: set[str] = set()
+
+
+def _log_once(key: str, message: str, *args: object) -> None:
+    if key not in _logged:
+        _logged.add(key)
+        logger.warning("Spanlight: " + message + " (logged once)", *args)
+
+
+def clean_text(field: str, value: object, limit: int) -> str | None:
+    """``value`` as text of 1 to ``limit`` characters, as the server accepts it, or ``None``."""
+    if value is None:
+        return None
+    try:
+        text = value if isinstance(value, str) else str(value)
+    except Exception:
+        _log_once(field + ".text", "trace %s cannot be turned into text; leaving it unset", field)
+        return None
+    if not text:
+        return None
+    if len(text) > limit:
+        _log_once(field + ".long", "trace %s over %d characters; cutting it", field, limit)
+        return text[:limit]
+    return text
+
+
+class TraceState:
+    """Mutable trace-level fields shared by every span of one trace.
+
+    Instances are shared by reference between parent and child spans
+    (including children running in other asyncio tasks), so an
+    :func:`~spanlight.update_trace` call anywhere in the trace is
+    visible to every span exported afterwards.
+    """
+
+    def __init__(
+        self,
+        *,
+        trace_id: str | None = None,
+        name: str | None = None,
+        environment: str | None = None,
+        release: str | None = None,
+    ) -> None:
+        self.trace_id = trace_id or new_trace_id()
+        self.name = clean_text("name", name, MAX_TEXT)
+        self.environment = clean_text("environment", environment, MAX_ENVIRONMENT)
+        self.release = clean_text("release", release, MAX_RELEASE)
+        self.user_id: str | None = None
+        self.session_id: str | None = None
+        self.tags: list[str] = []
+        self.metadata: dict[str, str] = {}
+        self._lock = threading.Lock()
+
+    def update(
+        self,
+        *,
+        name: str | None = None,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        tags: Iterable[str] | None = None,
+        metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        """Set trace-level fields. ``None`` or ``""`` leaves a field unchanged.
+
+        Tags accumulate; a single string is one tag. Metadata accumulates per key, a later value
+        replacing an earlier one; invalid entries are dropped (see :mod:`spanlight._metadata`).
+        """
+        cleaned = clean_metadata(metadata)
+        name = clean_text("name", name, MAX_TEXT)
+        user_id = clean_text("user_id", user_id, MAX_TEXT)
+        session_id = clean_text("session_id", session_id, MAX_TEXT)
+        single = isinstance(tags, str) or not isinstance(tags, Iterable | None)
+        new_tags = [clean_text("tag", tag, MAX_TAG) for tag in ([tags] if single else tags or ())]
+        with self._lock:
+            if name is not None:
+                self.name = name
+            if user_id is not None:
+                self.user_id = user_id
+            if session_id is not None:
+                self.session_id = session_id
+            for tag in new_tags:
+                if tag is None or tag in self.tags:
+                    continue
+                if len(self.tags) >= MAX_TAGS:
+                    _log_once("tags", "a trace keeps at most %d tags; dropping the rest", MAX_TAGS)
+                    break
+                self.tags.append(tag)
+            if cleaned:
+                self.metadata = merge_metadata(self.metadata, cleaned)
+
+    def to_payload(self) -> dict[str, JsonValue]:
+        """Return the ``trace`` object of the ingestion payload."""
+        with self._lock:
+            payload: dict[str, JsonValue] = {
+                "name": self.name,
+                "environment": self.environment,
+                "release": self.release,
+                "user_id": self.user_id,
+                "session_id": self.session_id,
+                "tags": list(self.tags),
+            }
+            # Only when set: a server older than trace metadata ignores the field anyway.
+            if self.metadata:
+                payload["metadata"] = dict(self.metadata)
+            return payload

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/_usage.py

@@ -13,6 +13,10 @@ from ._tiers import MAX_RAW_TIER_LENGTH, ServiceTier, normalize_tier
 
 logger = logging.getLogger("spanlight")
 
+# Outside these bounds the server rejects the whole span (token counts are stored as int4).
+_MAX_TOKENS = 2_000_000_000
+_MAX_WEB_SEARCH_REQUESTS = 100_000
+
 
 class SpanUsage:
     """Usage fields and setters of a span; see :meth:`set_usage`."""
@@ -62,23 +66,33 @@ class SpanUsage:
         standard. ``web_search_requests`` is the number of server-side web
         searches the call made; the provider wrappers read it from the
         response.
+
+        A count that is not a whole number from 0 up to the server's limit
+        (2,000,000,000 tokens, 100,000 searches) is ignored with a debug log,
+        because the server would reject the whole span.
         """
         if not self._mutable:
             return
-        if input_tokens is not None:
-            self.input_tokens = int(input_tokens)
-        if output_tokens is not None:
-            self.output_tokens = int(output_tokens)
-        if cached_tokens is not None:
-            self.cached_tokens = int(cached_tokens)
-        if cache_write_tokens is not None:
-            self.cache_write_tokens = int(cache_write_tokens)
-        if cache_write_1h_tokens is not None:
-            self.cache_write_1h_tokens = int(cache_write_1h_tokens)
+        counts = {
+            "input_tokens": (input_tokens, _MAX_TOKENS),
+            "output_tokens": (output_tokens, _MAX_TOKENS),
+            "cached_tokens": (cached_tokens, _MAX_TOKENS),
+            "cache_write_tokens": (cache_write_tokens, _MAX_TOKENS),
+            "cache_write_1h_tokens": (cache_write_1h_tokens, _MAX_TOKENS),
+            "web_search_requests": (web_search_requests, _MAX_WEB_SEARCH_REQUESTS),
+        }
+        for field, (value, limit) in counts.items():
+            if value is not None:
+                count = _count(value, limit)
+                if count is None:
+                    logger.debug("Ignoring %s: not a count the server accepts", field)
+                else:
+                    setattr(self, field, count)
         if service_tier is not None:
-            self._set_service_tier(str(service_tier))
-        if web_search_requests is not None:
-            self.web_search_requests = int(web_search_requests)
+            try:
+                self._set_service_tier(str(service_tier))
+            except Exception:
+                logger.debug("Ignoring a service tier that cannot be turned into text")
 
     def _set_service_tier(self, raw: str) -> None:
         if not raw.strip():
@@ -121,3 +135,12 @@ class SpanUsage:
         if self.web_search_requests is not None:
             usage["server_tool_use"] = {"web_search_requests": self.web_search_requests}
         return usage or None
+
+
+def _count(value: object, limit: int) -> int | None:
+    """``value`` as a count from 0 to ``limit``, or ``None`` when it is not one."""
+    try:
+        count = int(value)  # type: ignore[call-overload]
+    except Exception:
+        return None
+    return count if 0 <= count <= limit else None

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/_version.py

@@ -1,3 +1,3 @@
 """Package version, kept in one place."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/integrations/_common.py

@@ -9,13 +9,13 @@ observes streaming responses as the caller consumes them.
 
 from __future__ import annotations
 
+import functools
 import logging
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Mapping
 from typing import TYPE_CHECKING, Any
 
 from .._request_hash import request_hash
-from .._serialize import to_jsonable
 from .._span import Span
 from ._modifiers import SENTINEL_TYPE_NAMES, pricing_modifier_unknown
 from ._provider_errors import provider_request_id, record_response_details
@@ -93,17 +93,14 @@ def client_getter(spanlight: Spanlight | None) -> ClientGetter:
 def sanitize_request(kwargs: Mapping[str, Any]) -> dict[str, Any]:
     """Return the request parameters worth recording as span input.
 
-    Drops transport/auth options and the SDKs' "not given" sentinels, then
-    converts everything to JSON-compatible values.
+    Drops transport/auth options and the SDKs' "not given" sentinels. The values are
+    converted by ``Span.set_input``, which also records whether anything was cut.
     """
-    cleaned: dict[str, Any] = {}
-    for key, value in kwargs.items():
-        if key in _EXCLUDED_REQUEST_KEYS:
-            continue
-        if type(value).__name__ in SENTINEL_TYPE_NAMES:
-            continue
-        cleaned[key] = to_jsonable(value)
-    return cleaned
+    return {
+        key: value
+        for key, value in kwargs.items()
+        if key not in _EXCLUDED_REQUEST_KEYS and type(value).__name__ not in SENTINEL_TYPE_NAMES
+    }
 
 
 def is_raw_response_call(kwargs: Mapping[str, Any]) -> bool:
@@ -189,9 +186,9 @@ def start_llm_span(
         span = client.start_span(endpoint.span_name(kwargs), kind="llm")
         model = kwargs.get("model")
         span.set_model(model if isinstance(model, str) else None, provider=endpoint.provider)
-        request = sanitize_request(kwargs)
-        span.set_request_hash(_request_hash_or_none(model, request))
-        span.set_input(request)
+        span.set_input(sanitize_request(kwargs))
+        # From the request as recorded, the same JSON values the server hashes.
+        span.set_request_hash(_request_hash_or_none(model, span.input))
         if kwargs.get("stream") is True:
             span.set_attribute("request.stream", True)
         modifier = pricing_modifier_unknown(kwargs)
@@ -245,3 +242,18 @@ def patch_method(
     if original is None or getattr(original, WRAPPED_MARKER, False):
         return
     setattr(resource, attribute, make_wrapper(original))
+
+
+def patch_copies(client: Any, instrument: Callable[[Any], Any]) -> None:
+    """Instrument the clients that ``client.copy()`` and ``client.with_options()`` return, too."""
+
+    def make_wrapper(original: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(original)
+        def copy(*args: Any, **kwargs: Any) -> Any:
+            return instrument(original(*args, **kwargs))
+
+        setattr(copy, WRAPPED_MARKER, True)
+        return copy
+
+    for attribute in ("copy", "with_options"):
+        patch_method(client, attribute, make_wrapper)

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/integrations/anthropic.py

@@ -1,8 +1,10 @@
 """Instrumentation for the official ``anthropic`` Python SDK.
 
 :func:`wrap_anthropic` patches ``messages.create`` (including
-``stream=True``), the ``messages.stream(...)`` helper and
-``messages.batches.results`` on one client instance, sync or async.
+``stream=True``), ``messages.parse``, the ``messages.stream(...)`` helper and
+``messages.batches.results`` on one client instance, sync or async, on its beta
+surface (``client.beta.messages``) and on the clients its ``copy()`` and
+``with_options()`` return.
 
 Token accounting: Anthropic reports ``input_tokens`` *excluding* prompt-cache
 reads and writes. To keep one meaning across providers, spans record
@@ -25,9 +27,11 @@ from ._anthropic_message import PROVIDER, record_message_metadata, record_usage
 from ._anthropic_stream import AsyncStreamManager, MessagesStreamAccumulator, SyncStreamManager
 from ._common import (
     WRAPPED_MARKER,
+    ClientGetter,
     Endpoint,
     client_getter,
     get_field,
+    patch_copies,
     patch_method,
     pop_prompt,
 )
@@ -51,7 +55,10 @@ def wrap_anthropic(client: ClientT, *, spanlight: Spanlight | None = None) -> Cl
     are recorded and re-raised unchanged. Each result read through
     ``messages.batches.results`` becomes an ``llm`` span at the batch rate in
     a trace of its own, with ids fixed by the batch, so reading a batch twice
-    records it once. Wrapping twice is harmless.
+    records it once. ``messages.parse`` and the same methods of
+    ``client.beta.messages`` are traced too, and so are clients made with
+    ``client.with_options(...)`` or ``client.copy(...)``. Wrapping twice is
+    harmless.
 
     Args:
         client: The Anthropic client to instrument.
@@ -71,15 +78,26 @@ def _instrument(client: Any, spanlight: Spanlight | None) -> None:
     from anthropic import AsyncStream, Stream
     from anthropic.resources.messages import AsyncMessages
 
-    from ._anthropic_batch import patch_batch_results
-
     get_client = client_getter(spanlight)
     endpoint = MessagesEndpoint(PROVIDER, (Stream, AsyncStream))
-    messages = client.messages
-    is_async = isinstance(messages, AsyncMessages)
+    _instrument_messages(client.messages, endpoint, get_client, AsyncMessages)
+    patch_copies(client, lambda copy: wrap_anthropic(copy, spanlight=spanlight))
+    # Fast mode, compaction and the tool runner exist only on the beta surface.
+    from anthropic.resources.beta.messages import AsyncMessages as AsyncBetaMessages
+
+    _instrument_messages(client.beta.messages, endpoint, get_client, AsyncBetaMessages)
+
+
+def _instrument_messages(
+    messages: Any, endpoint: MessagesEndpoint, get_client: ClientGetter, async_cls: type
+) -> None:
+    from ._anthropic_batch import patch_batch_results
 
+    is_async = isinstance(messages, async_cls)
     wrap = wrap_async_method if is_async else wrap_sync_method
-    patch_method(messages, "create", lambda original: wrap(original, endpoint, get_client))
+    # `parse` is a separate request, not a call to `create`, so it needs its own span.
+    for name in ("create", "parse"):
+        patch_method(messages, name, lambda original: wrap(original, endpoint, get_client))
 
     manager_cls = AsyncStreamManager if is_async else SyncStreamManager
 

{spanlight-0.2.0 → spanlight-0.2.1}/src/spanlight/integrations/openai.py

@@ -13,7 +13,15 @@ from collections.abc import Mapping
 from typing import TYPE_CHECKING, Any, TypeVar
 
 from .._span import Span
-from ._common import ClientGetter, Endpoint, as_int, client_getter, get_field, patch_method
+from ._common import (
+    ClientGetter,
+    Endpoint,
+    as_int,
+    client_getter,
+    get_field,
+    patch_copies,
+    patch_method,
+)
 from ._modifiers import has_request_option
 from ._openai_response import (
     chat_output,
@@ -48,7 +56,8 @@ def wrap_openai(
     Every ``chat.completions.create`` and ``responses.create`` call becomes an
     ``llm`` span with the model, token usage, time-to-first-token (streams),
     sanitized request parameters and the response. Errors are recorded and
-    re-raised unchanged. Wrapping the same client twice is harmless.
+    re-raised unchanged. Clients made with ``client.with_options(...)`` or
+    ``client.copy(...)`` are instrumented too. Wrapping the same client twice is harmless.
 
     Args:
         client: The OpenAI client to instrument.
@@ -90,6 +99,7 @@ def _instrument(client: Any, spanlight: Spanlight | None, provider: str) -> None
         _patch_create(
             resource, endpoint, get_client, is_async=isinstance(resource, async_resources)
         )
+    patch_copies(client, lambda copy: wrap_openai(copy, spanlight=spanlight, provider=provider))
 
 
 def _patch_create(

{spanlight-0.2.0 → spanlight-0.2.1}/tests/test_anthropic.py

@@ -251,6 +251,27 @@ async def test_async_messages_create(tracer, ingest):
     assert span["usage"]["output_tokens"] == 9
 
 
+def test_with_options_and_copy_clients_are_traced(tracer, ingest):
+    provider = MockProvider(json_response(ANTHROPIC_MESSAGE))
+    client = make_client(provider, tracer)
+
+    client.with_options(timeout=5).messages.create(model=MODEL, max_tokens=8, messages=MESSAGES)
+    client.copy().messages.create(model=MODEL, max_tokens=8, messages=MESSAGES)
+
+    assert len(flushed_spans(tracer, ingest)) == 2
+
+
+def test_beta_messages_are_traced(tracer, ingest):
+    client = make_client(MockProvider(json_response(ANTHROPIC_MESSAGE)), tracer)
+    client.beta.messages.create(model=MODEL, max_tokens=8, messages=MESSAGES, betas=["x-1"])
+    streaming = make_client(MockProvider(sse_response(anthropic_text_stream())), tracer)
+    with streaming.beta.messages.stream(model=MODEL, max_tokens=8, messages=MESSAGES) as stream:
+        "".join(stream.text_stream)
+
+    spans = flushed_spans(tracer, ingest)
+    assert [span["usage"]["input_tokens"] for span in spans] == [1515, 25]
+
+
 def test_create_with_stream_true(tracer, ingest):
     provider = MockProvider(sse_response(anthropic_text_stream()))
     client = make_client(provider, tracer)

{spanlight-0.2.0 → spanlight-0.2.1}/tests/test_decorator.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import re
 
 import pytest
@@ -389,6 +390,24 @@ async def test_async_generator_error_and_early_close(tracer, ingest):
     assert ingest.span_named("endless")["output"] == [0, 1]
 
 
+def test_async_generator_abandoned_by_break_is_not_an_error(tracer, ingest):
+    @tracer.observe(name="abandoned")
+    async def numbers():
+        for index in range(10):
+            yield index
+
+    async def main() -> None:
+        async for value in numbers():
+            if value == 1:
+                break
+
+    # asyncio closes the abandoned generator by cancelling its `aclose()` at loop shutdown.
+    asyncio.run(main())
+
+    flushed_spans(tracer, ingest)
+    assert ingest.span_named("abandoned")["status"] == "ok"
+
+
 # ---------------------------------------------------------------------- #
 # Disabled mode
 # ---------------------------------------------------------------------- #

{spanlight-0.2.0 → spanlight-0.2.1}/tests/test_exporter.py

@@ -331,6 +331,19 @@ def test_unexpected_transport_failure_never_escapes(make_exporter, ingest):
     assert exporter.sent_count == 1
 
 
+def test_an_unencodable_span_loses_only_itself(make_exporter, ingest, caplog):
+    exporter = make_exporter()
+    exporter.export(make_span(1))
+    exporter.export({**make_span(2), "attributes": {"huge": 10**5000}})
+    exporter.export(make_span(3))
+
+    with caplog.at_level(logging.WARNING, logger="spanlight"):
+        assert exporter.flush(timeout=5)
+    assert [span["span_id"] for span in ingest.spans] == [f"{1:016x}", f"{3:016x}"]
+    assert exporter.failed_count == 1
+    assert f"{2:016x}" in caplog.text
+
+
 def test_flush_returns_false_when_the_timeout_expires(make_exporter, ingest):
     release = threading.Event()
 

{spanlight-0.2.0 → spanlight-0.2.1}/tests/test_spans_and_context.py

@@ -192,6 +192,38 @@ def test_manual_record_error_with_message(tracer, ingest):
     assert exported["status_message"] == "schema mismatch"
 
 
+def test_exception_whose_str_raises_is_reraised_unchanged(tracer, ingest):
+    class Unprintable(Exception):
+        def __str__(self) -> str:
+            raise RuntimeError("no text")
+
+    with pytest.raises(Unprintable), tracer.span("fails"):
+        raise Unprintable
+
+    exported = flushed_spans(tracer, ingest)[0]
+    assert exported["status"] == "error"
+    assert exported["status_message"] == "Unprintable"
+
+
+def test_setters_never_raise_on_bad_values(tracer, ingest):
+    class NoText:
+        def __str__(self) -> str:
+            raise RuntimeError("no text")
+
+    with tracer.span("bad-values", attributes=[("pairs", "work")]) as span:  # type: ignore[arg-type]
+        span.set_usage(input_tokens="abc", output_tokens=-1, cached_tokens=3)  # type: ignore[arg-type]
+        span.set_usage(web_search_requests=10**6, service_tier=NoText())  # type: ignore[arg-type]
+        span.set_attributes(None)  # type: ignore[arg-type]
+        span.set_attribute(NoText(), 1)  # type: ignore[arg-type]
+        span.record_error(None)
+
+    exported = flushed_spans(tracer, ingest)[0]
+    assert exported["usage"] == {"cached_tokens": 3}
+    assert exported["attributes"] == {"pairs": "work"}
+    assert exported["status"] == "error"
+    assert exported["status_message"] is None
+
+
 def test_setters_after_end_are_ignored(tracer, ingest):
     with tracer.span("done") as span:
         span.set_output("final")
@@ -266,6 +298,28 @@ def test_update_trace_applies_to_all_spans_of_the_trace(tracer, ingest):
     }
 
 
+def test_trace_fields_are_made_to_fit_the_server_limits(ingest):
+    tracer = spanlight.Spanlight(
+        api_key="spl_live_testprefix_testsecret",
+        host="http://spanlight.test",
+        environment="e" * 65,
+        release="r" * 129,
+        transport=ingest.transport(),
+    )
+    with tracer.span("root"):
+        spanlight.update_trace(name="", user_id="", session_id="s" * 257, tags="beta")
+        spanlight.update_trace(user_id=42, tags=[*map(str, range(25)), "t" * 65, ""])  # type: ignore[arg-type]
+
+    trace = flushed_spans(tracer, ingest)[0]["trace"]
+    tracer.shutdown(timeout=2)
+    assert trace["name"] == "root"
+    assert trace["environment"] == "e" * 64
+    assert trace["release"] == "r" * 128
+    assert trace["user_id"] == "42"
+    assert trace["session_id"] == "s" * 256
+    assert trace["tags"] == ["beta", *map(str, range(19))]
+
+
 def test_update_trace_outside_a_span_is_a_no_op():
     spanlight.update_trace(user_id="nobody")  # must not raise
 
@@ -343,3 +397,17 @@ def test_threads_need_an_explicit_context_copy(tracer, ingest):
         copied.join()
 
     assert seen == {"plain": None, "copied": "main"}
+
+
+def test_a_200_kb_input_is_sent_whole_and_a_cut_attribute_flags_the_span(tracer, ingest):
+    context = "retrieved passage " * 12_000  # about 216 KB, one string
+    with tracer.span("rag", kind="llm") as span:
+        span.set_input({"messages": [{"role": "user", "content": context}]})
+    with tracer.span("long-attribute") as span:
+        span.set_attribute("note", "x" * 40_000)
+
+    by_name = {item["name"]: item for item in flushed_spans(tracer, ingest)}
+    assert by_name["rag"]["input"]["messages"][0]["content"] == context
+    assert "truncated" not in by_name["rag"]
+    assert len(by_name["long-attribute"]["attributes"]["note"]) < 40_000
+    assert by_name["long-attribute"]["truncated"] is True

{spanlight-0.2.0 → spanlight-0.2.1}/uv.lock

@@ -838,7 +838,7 @@ wheels = [
 
 [[package]]
 name = "spanlight"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

spanlight-0.2.0/src/spanlight/_trace_state.py

@@ -1,83 +0,0 @@
-"""Trace-level state shared by every span of one trace."""
-
-from __future__ import annotations
-
-import threading
-from collections.abc import Iterable, Mapping
-
-from ._ids import new_trace_id
-from ._metadata import clean_metadata, merge_metadata
-from ._serialize import JsonValue
-
-
-class TraceState:
-    """Mutable trace-level fields shared by every span of one trace.
-
-    Instances are shared by reference between parent and child spans
-    (including children running in other asyncio tasks), so an
-    :func:`~spanlight.update_trace` call anywhere in the trace is
-    visible to every span exported afterwards.
-    """
-
-    def __init__(
-        self,
-        *,
-        trace_id: str | None = None,
-        name: str | None = None,
-        environment: str | None = None,
-        release: str | None = None,
-    ) -> None:
-        self.trace_id = trace_id or new_trace_id()
-        self.name = name
-        self.environment = environment
-        self.release = release
-        self.user_id: str | None = None
-        self.session_id: str | None = None
-        self.tags: list[str] = []
-        self.metadata: dict[str, str] = {}
-        self._lock = threading.Lock()
-
-    def update(
-        self,
-        *,
-        name: str | None = None,
-        user_id: str | None = None,
-        session_id: str | None = None,
-        tags: Iterable[str] | None = None,
-        metadata: Mapping[str, object] | None = None,
-    ) -> None:
-        """Set trace-level fields. ``None`` leaves a field unchanged.
-
-        Tags accumulate. Metadata accumulates per key, a later value replacing an earlier one;
-        invalid entries are dropped (see :mod:`spanlight._metadata`).
-        """
-        cleaned = clean_metadata(metadata)
-        with self._lock:
-            if name is not None:
-                self.name = name
-            if user_id is not None:
-                self.user_id = user_id
-            if session_id is not None:
-                self.session_id = session_id
-            if tags is not None:
-                for tag in tags:
-                    if tag not in self.tags:
-                        self.tags.append(str(tag))
-            if cleaned:
-                self.metadata = merge_metadata(self.metadata, cleaned)
-
-    def to_payload(self) -> dict[str, JsonValue]:
-        """Return the ``trace`` object of the ingestion payload."""
-        with self._lock:
-            payload: dict[str, JsonValue] = {
-                "name": self.name,
-                "environment": self.environment,
-                "release": self.release,
-                "user_id": self.user_id,
-                "session_id": self.session_id,
-                "tags": list(self.tags),
-            }
-            # Only when set: a server older than trace metadata ignores the field anyway.
-            if self.metadata:
-                payload["metadata"] = dict(self.metadata)
-            return payload