telemetry-dev 0.2.7__tar.gz → 0.2.9__tar.gz

{telemetry_dev-0.2.7 → telemetry_dev-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.7
+Version: 0.2.9
 Summary: telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics
 Keywords: telemetry,opentelemetry,llm,genai,tracing,observability
 Author: telemetry.dev
@@ -159,14 +159,19 @@ the core SDK with provider integrations to enable the new metric.
 | `log_level` | `"warn"` | SDK diagnostics level: `debug`/`info`/`warn`/`error`/`silent`. |
 | `capture_input`, `capture_output` | `True` | Global content-capture defaults. |
 | `mask` | `None` | `Callable[[Any, MaskContext], Any]` redaction hook, runs before JSON serialization on input/output/log messages (`MaskContext.key` is the attribute being written). Not applied to correlation identifiers. |
-| `max_attribute_length` | `65536` | Per-content-attribute cap; truncated values get an ASCII `...[truncated]` marker appended. |
+| `max_attribute_length` | `65536` | Non-negative integer per-content-attribute cap. Invalid values call `on_error`, do not raise into application code, and install a disabled client; truncated values use the ASCII `...[truncated]` marker, or its prefix when the cap is shorter than the marker. The cap also applies, with the marker, to string metadata and log attributes; any other string attribute is cut at the cap without a marker, except that a cap of `0` leaves those at 65536. |
 | `span_filter` | `None` | Export predicate `Callable[[ReadableSpan], bool]`. |
 | `sampler` | OTel environment configuration | OTel `Sampler` that overrides environment settings. Session roots use its root policy. Real parents keep their sampling decisions. |
-| `on_error` | `None` | Receives every internal SDK error; the SDK never raises. |
+| `on_error` | `None` | Receives internal SDK errors; repeated instrumentation failures from one stream may be coalesced into one report. The SDK never raises them into application code. |
 | `disable_atexit` | `False` | Skip the automatic atexit shutdown. |
 | `timeout` | `10.0` | OTLP HTTP timeout in seconds. |
 | `span_exporter`, `log_exporter`, `metric_reader` | `None` | Test seams / offline mode; any of them enables the client without an API key. |
 
+`capture_input=False` and `capture_output=False` omit captured content. Provider integrations may
+still record non-content metadata such as response IDs and models, finish reasons, usage, timing,
+and errors. Capture flags do not gate stop sequences, tool descriptions and definitions (`gen_ai.tool.description`, `gen_ai.tool.definitions`), caller-supplied metadata or raw attributes,
+or exception messages and stack traces; redact those separately when needed.
+
 Session roots share trace IDs from the API key and session ID. The hash matches the TypeScript SDK.
 The SDK uses the configured OTel sampling policy, not the synthetic parent's flags.
 For example, `init(sampler=ParentBased(TraceIdRatioBased(0.1)))` samples sessions with OTel's ratio sampler.

{telemetry_dev-0.2.7 → telemetry_dev-0.2.9}/README.md

@@ -135,14 +135,19 @@ the core SDK with provider integrations to enable the new metric.
 | `log_level` | `"warn"` | SDK diagnostics level: `debug`/`info`/`warn`/`error`/`silent`. |
 | `capture_input`, `capture_output` | `True` | Global content-capture defaults. |
 | `mask` | `None` | `Callable[[Any, MaskContext], Any]` redaction hook, runs before JSON serialization on input/output/log messages (`MaskContext.key` is the attribute being written). Not applied to correlation identifiers. |
-| `max_attribute_length` | `65536` | Per-content-attribute cap; truncated values get an ASCII `...[truncated]` marker appended. |
+| `max_attribute_length` | `65536` | Non-negative integer per-content-attribute cap. Invalid values call `on_error`, do not raise into application code, and install a disabled client; truncated values use the ASCII `...[truncated]` marker, or its prefix when the cap is shorter than the marker. The cap also applies, with the marker, to string metadata and log attributes; any other string attribute is cut at the cap without a marker, except that a cap of `0` leaves those at 65536. |
 | `span_filter` | `None` | Export predicate `Callable[[ReadableSpan], bool]`. |
 | `sampler` | OTel environment configuration | OTel `Sampler` that overrides environment settings. Session roots use its root policy. Real parents keep their sampling decisions. |
-| `on_error` | `None` | Receives every internal SDK error; the SDK never raises. |
+| `on_error` | `None` | Receives internal SDK errors; repeated instrumentation failures from one stream may be coalesced into one report. The SDK never raises them into application code. |
 | `disable_atexit` | `False` | Skip the automatic atexit shutdown. |
 | `timeout` | `10.0` | OTLP HTTP timeout in seconds. |
 | `span_exporter`, `log_exporter`, `metric_reader` | `None` | Test seams / offline mode; any of them enables the client without an API key. |
 
+`capture_input=False` and `capture_output=False` omit captured content. Provider integrations may
+still record non-content metadata such as response IDs and models, finish reasons, usage, timing,
+and errors. Capture flags do not gate stop sequences, tool descriptions and definitions (`gen_ai.tool.description`, `gen_ai.tool.definitions`), caller-supplied metadata or raw attributes,
+or exception messages and stack traces; redact those separately when needed.
+
 Session roots share trace IDs from the API key and session ID. The hash matches the TypeScript SDK.
 The SDK uses the configured OTel sampling policy, not the synthetic parent's flags.
 For example, `init(sampler=ParentBased(TraceIdRatioBased(0.1)))` samples sessions with OTel's ratio sampler.

{telemetry_dev-0.2.7 → telemetry_dev-0.2.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.7"
+version = "0.2.9"
 description = "telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics"
 readme = "README.md"
 license = "MIT"

{telemetry_dev-0.2.7 → telemetry_dev-0.2.9}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.7"
+version = "0.2.9"
 description = "telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics"
 readme = "README.md"
 license = "MIT"

{telemetry_dev-0.2.7 → telemetry_dev-0.2.9}/src/telemetry_dev/_capture.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterable
+import re
+from collections.abc import Iterable, Mapping, Sequence
 from itertools import chain
 from typing import Final, cast
 
@@ -11,6 +12,36 @@ _DEFAULT_MAX_ITEMS: Final = 1024
 _MAX_DEPTH: Final = 32
 _BASE_ITEM_BYTES: Final = 16
 
+# Code points whose JSON form is longer than their UTF-8 form, mapped to the extra bytes.
+_SHORT_ESCAPE_EXTRA: Final = 1  # '"', '\\', \b \t \n \f \r: 1 byte raw, 2 escaped
+_CONTROL_ESCAPE_EXTRA: Final = 5  # other code points below 0x20: 1 byte raw, 6 as \u00XX
+_SURROGATE_ESCAPE_EXTRA: Final = 3  # a surrogate code point: 3 bytes raw, 6 as \uXXXX
+_JSON_ESCAPED: Final = re.compile('["\\\\\x00-\x1f\ud800-\udfff]')
+_JSON_STRING_CHUNK: Final = 4096
+
+
+def _escape_extra(character: str) -> int:
+    code = ord(character)
+    if character in '"\\\b\t\n\f\r':
+        return _SHORT_ESCAPE_EXTRA
+    if code < 0x20:
+        return _CONTROL_ESCAPE_EXTRA
+    return _SURROGATE_ESCAPE_EXTRA
+
+
+def _json_string_bytes(value: str, limit: int | None) -> int:
+    # Every code point costs at least one byte, so a string longer than the limit needs no scan.
+    if limit is not None and len(value) > limit:
+        return len(value)
+    size = 0
+    for start in range(0, len(value), _JSON_STRING_CHUNK):
+        chunk = value[start : start + _JSON_STRING_CHUNK]
+        size += len(chunk.encode("utf-8", "surrogatepass"))
+        size += sum(_escape_extra(match.group()) for match in _JSON_ESCAPED.finditer(chunk))
+        if limit is not None and size > limit:
+            return size
+    return size
+
 
 class CaptureBudget:
     """Track a hard byte and item budget before retaining streamed provider data."""
@@ -32,6 +63,18 @@ class CaptureBudget:
             max_bytes=client.max_attribute_length if client is not None else _DEFAULT_MAX_BYTES
         )
 
+    @staticmethod
+    def json_string_bytes(value: str, limit: int | None = None) -> int:
+        """Return the UTF-8 bytes ``value`` occupies inside a JSON string, without the quotes.
+
+        Matches the TypeScript SDK's measure: ``"``, ``\\``, and ``\\b \\t \\n \\f \\r`` cost 2
+        bytes, other control characters cost 6 (``\\u00XX``), and every surrogate code point
+        costs 6 (``\\uXXXX``); anything else costs its UTF-8 width. The budget charges a string
+        this plus its per-item cost, which covers the quotes and separators. Counting stops
+        once the total passes ``limit``, so a result above ``limit`` is only a lower bound.
+        """
+        return _json_string_bytes(value, limit)
+
     @property
     def remaining_bytes(self) -> int:
         """Return bytes still available for retained capture state."""
@@ -98,20 +141,9 @@ class CaptureBudget:
         if value is None or isinstance(value, bool | int | float):
             return byte_count, item_count
         if isinstance(value, str):
-            for character in value:
-                codepoint = ord(character)
-                byte_count += (
-                    1
-                    if codepoint <= 0x7F
-                    else 2
-                    if codepoint <= 0x7FF
-                    else 3
-                    if codepoint <= 0xFFFF
-                    else 4
-                )
-                if byte_count > remaining_bytes:
-                    return None
-            return byte_count, item_count
+            # Mapping keys come through here too, so they are charged at their escaped size.
+            byte_count += _json_string_bytes(value, remaining_bytes - byte_count)
+            return (byte_count, item_count) if byte_count <= remaining_bytes else None
         if isinstance(value, bytes | bytearray | memoryview):
             length = value.nbytes if isinstance(value, memoryview) else len(value)
             # Structured attributes serialize binary values as base64 text.
@@ -123,16 +155,18 @@ class CaptureBudget:
             return byte_count, item_count
         seen.add(value_id)
         try:
-            mapping: dict[object, object] | None = None
+            mapping: Mapping[object, object] | None = None
             children: Iterable[object] = ()
-            if isinstance(value, dict):
-                mapping = cast("dict[object, object]", value)
-            elif isinstance(value, list | tuple | set | frozenset):
+            if isinstance(value, Mapping):
+                mapping = cast("Mapping[object, object]", value)
+            elif isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
+                children = cast("Iterable[object]", value)
+            elif isinstance(value, set | frozenset):
                 children = cast("Iterable[object]", value)
             else:
                 attributes = getattr(value, "__dict__", None)
-                if isinstance(attributes, dict):
-                    mapping = cast("dict[object, object]", attributes)
+                if isinstance(attributes, Mapping):
+                    mapping = cast("Mapping[object, object]", attributes)
 
             if mapping is not None:
                 children = chain.from_iterable(mapping.items())

{telemetry_dev-0.2.7 → telemetry_dev-0.2.9}/src/telemetry_dev/_client.py

@@ -49,7 +49,7 @@ from ._metrics import (
 )
 from ._processor import ExportMode, StampingSpanProcessor
 from ._semconv import SCOPE_NAME
-from ._serialize import Mask, serialize_content
+from ._serialize import DEFAULT_MAX_ATTRIBUTE_LENGTH, Mask, serialize_content
 
 _lock = threading.RLock()
 _client: Client | None = None
@@ -182,14 +182,16 @@ class Client:
         )
 
         # The funnel keeps capped content (marker included) within max_attribute_length, so
-        # the backstop can use the same cap for raw attributes set outside the funnel.
+        # the backstop can use the same cap for raw attributes set outside the funnel. A zero
+        # cap only drops content; as a backstop it would blank every string attribute.
+        backstop_length = max_attribute_length or DEFAULT_MAX_ATTRIBUTE_LENGTH
         self._tracer_provider = TracerProvider(
             resource=resource,
             sampler=sampler,
             shutdown_on_exit=False,
             span_limits=SpanLimits(
-                max_attribute_length=max_attribute_length,
-                max_span_attribute_length=max_attribute_length,
+                max_attribute_length=backstop_length,
+                max_span_attribute_length=backstop_length,
             ),
         )
         self._tracer_provider.sampler = SessionSampler(self._tracer_provider.sampler)
@@ -365,6 +367,14 @@ def init(
     try:
         if session_mode not in ("explicit", "process"):
             raise ValueError(f"invalid session_mode: {session_mode!r}")
+        raw_max_attribute_length: Any = max_attribute_length
+        if (
+            isinstance(raw_max_attribute_length, bool)
+            or not isinstance(raw_max_attribute_length, int)
+            or raw_max_attribute_length < 0
+        ):
+            raise ValueError("max_attribute_length must be a non-negative integer")
+        max_attribute_length = raw_max_attribute_length
         client = Client(
             config=config,
             enabled=effective_enabled,

{telemetry_dev-0.2.7 → telemetry_dev-0.2.9}/src/telemetry_dev/_serialize.py

@@ -31,9 +31,9 @@ def truncate(text: str, max_len: int) -> str:
     encoded = text.encode("utf-16-le")
     if len(encoded) <= max_len * 2:
         return text
-    # Total stays within max_len so the provider's attribute_value_length_limit backstop,
-    # set to the same cap, never slices the marker off.
-    head = encoded[: max(max_len - len(TRUNCATION_MARKER), 0) * 2]
+    if max_len < len(TRUNCATION_MARKER):
+        return TRUNCATION_MARKER[: max(max_len, 0)]
+    head = encoded[: (max_len - len(TRUNCATION_MARKER)) * 2]
     try:
         return head.decode("utf-16-le") + TRUNCATION_MARKER
     except UnicodeDecodeError:

{telemetry_dev-0.2.7 → telemetry_dev-0.2.9}/src/telemetry_dev/_spans.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import math
+import sys
 import threading
 import time
 import traceback
@@ -267,7 +268,7 @@ def _fields_to_attributes(
         for key, value in raw.items():
             attr = coerce_attr_value(
                 value,
-                max_len=client.max_attribute_length,
+                max_len=sys.maxsize,
                 key=key,
                 on_error=client.on_error,
             )
@@ -379,6 +380,22 @@ class SpanHandle:
         self._context_token: Token[Context] | None = None
         self._ended = False
 
+    @property
+    def capture_output(self) -> bool:
+        return self._state.capture_output if self._state is not None else False
+
+    @property
+    def capture_masked(self) -> bool:
+        return self._client is not None and self._client.mask is not None
+
+    @property
+    def max_attribute_length(self) -> int:
+        return self._client.max_attribute_length if self._client is not None else 0
+
+    def report_error(self, cause: BaseException) -> None:
+        if self._client is not None:
+            self._client.report("provider instrumentation failed", cause)
+
     def _recording(self) -> bool:
         return (
             self._client is not None