telemetry-dev 0.2.8__tar.gz → 0.2.10__tar.gz

{telemetry_dev-0.2.8 → telemetry_dev-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.8
+Version: 0.2.10
 Summary: telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics
 Keywords: telemetry,opentelemetry,llm,genai,tracing,observability
 Author: telemetry.dev
@@ -28,6 +28,8 @@ telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and m
 ergonomic functions over OTel spans (`gen_ai.*` semantic conventions), exported as OTLP
 protobuf to the telemetry.dev ingest.
 
+Docs: https://telemetry.dev/docs/sdk/python
+
 ## Install
 
 ```sh
@@ -100,6 +102,7 @@ later `init()` generates a new ID. It is not persisted across processes.
 | `@observe` / `@observe(name=, type=, capture_input=, capture_output=, attributes=)` | Wrap a sync/async function (or generator) in a span. Arguments become `input` (param-name dict, `self`/`cls` dropped), the return value becomes `output`, exceptions are captured and re-raised. |
 | `start_span(name, *, type="span", ...) -> SpanHandle` | Start a span. `with` activates it in the current context; without `with` it is a detached handle you must `.end()`. |
 | `SpanHandle.update(**fields)` / `.end(**fields, end_time=)` / `.record_output_chunk(timestamp_ms=None)` / `.traceparent()` | Update attributes, end, record arrival of a non-empty output chunk, or read the W3C traceparent. |
+| `SpanHandle.serialize_content(value, key) -> str \| None` | Prepare content an integration writes outside `input` and `output`, such as an error message or a raw attribute, the way `input` and `output` are prepared: the configured `mask` with `key`, JSON serialization (strings pass through), then truncation to `max_attribute_length`. Returns `None` when the mask raises (reported through `on_error`) or the value cannot be serialized; write nothing then. Does not check `capture_input` / `capture_output`. Integrations that support older cores should treat a missing method as a configured mask. |
 | `update_current_span(**fields)` | Apply the update field set to the currently active span (no-op without one). |
 | `propagate_attributes(*, user_id=, session_id=, metadata=)` | Context manager stamping `user.id` / `gen_ai.conversation.id` / `td.metadata.*` on every span and log record started inside (threads/asyncio included via contextvars). |
 | `log(message, *, level="info", event_name=None, attributes=None)` | Emit an OTLP log record to `/v1/logs`, correlated with the current trace. Levels: `debug`/`info`/`warn`/`error` (`"warning"` is accepted as an alias of `warn`). |
@@ -154,11 +157,12 @@ the core SDK with provider integrations to enable the new metric.
 | --- | --- | --- |
 | `api_key`, `base_url`, `environment`, `service_name` | env vars | Connection + resource settings. |
 | `enabled` | `True` | `False` = hard kill switch (tests). |
+| `session_mode` | `"explicit"` | `"process"` groups otherwise uncorrelated spans and logs under one generated session ID per `init()` (see [Environment variables](#environment-variables)). Other values call `on_error` and install a disabled client. |
 | `register_global` | `False` | Also register the tracer provider globally. Applies a default export filter (only `telemetry_dev`-scoped spans are exported); pass `span_filter=lambda s: True` to export everything. |
 | `export_mode` | `"batched"` | `"immediate"` exports synchronously per span/log (serverless). |
 | `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. |
+| `mask` | `None` | `Callable[[Any, MaskContext], Any]` redaction hook, runs before JSON serialization on input/output/log messages and `SpanHandle.serialize_content` (`MaskContext.key` is the attribute being written). Not applied to correlation identifiers. |
 | `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. |
@@ -172,6 +176,11 @@ still record non-content metadata such as response IDs and models, finish reason
 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.
 
+`mask` receives input and output content, system instructions, log messages, and content that
+integrations pass to `SpanHandle.serialize_content`. `MaskContext.key` names the attribute being
+written. It does not receive span or propagated `metadata`, raw `attributes`, log attributes, or
+exception messages and stack traces; redact those separately.
+
 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.
@@ -252,6 +261,68 @@ safe to attach unconditionally, with only a debug log. Auto-metrics are on by de
 GenAI spans, use the `service_name` / `environment` resource settings above, and are skipped
 without an API key.
 
+### Native Claude SDK spans
+
+The Python `anthropic` SDK 1.14.0 and later emits OpenTelemetry spans natively. The Claude SDK uses the global tracer provider of the application.
+To send these spans to telemetry.dev, register a global tracer provider with `TelemetrySpanProcessor`:
+
+```sh
+pip install telemetry-dev "anthropic>=1.14.0"
+```
+
+```python
+from anthropic import Anthropic
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from telemetry_dev.otel import TelemetrySpanProcessor
+
+provider = TracerProvider()
+provider.add_span_processor(TelemetrySpanProcessor())
+trace.set_tracer_provider(provider)
+
+client = Anthropic()
+client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=256,
+    messages=[{"role": "user", "content": "Say hello."}],
+)
+
+provider.shutdown()
+```
+
+If you use `telemetry_dev.init(register_global=True)`, also pass `span_filter=lambda span: True`. The default filter of that mode exports only the spans of this SDK.
+
+By default, the spans contain metadata only. To also send prompts and responses, set `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content`. The client reads this variable one time, when you make the client.
+
+Do not use the native spans and `telemetry-dev-anthropic` together. If you use the two, each request has two spans.
+
+You can also send the native spans without this package. Use an OTLP/HTTP protobuf exporter:
+
+```sh
+pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
+```
+
+```python
+import os
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+exporter = OTLPSpanExporter(
+    endpoint="https://ingest.telemetry.dev/v1/traces",
+    headers={"Authorization": f"Bearer {os.environ['TELEMETRY_DEV_API_KEY']}"},
+)
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(exporter))
+trace.set_tracer_provider(provider)
+```
+
+The Claude API can also send server-side spans to telemetry.dev through a Console destination. Set the endpoint to `https://ingest.telemetry.dev`. Set the `Authorization` header to `Bearer <telemetry.dev API key>`. For more information, refer to [Claude Platform](https://telemetry.dev/docs/integrations/claude-platform).
+
+When the SDK and the Claude API send the spans of a request to the same telemetry.dev project, telemetry.dev counts the tokens of the request one time, from the API span. The SDK span stays in the trace with no tokens. telemetry.dev matches the two spans by the request ID or the response ID, so the API span does not have to be a child of the SDK span. If the Console destination uses an API key that is scoped to one environment, its API spans take over only the SDK spans of that environment.
+
 ## Limitations
 
 - `register_global=True` cannot be undone on `shutdown()`: OpenTelemetry Python has no public
@@ -274,3 +345,7 @@ uv build                # build wheel + sdist
 
 `examples/quickstart.py` is runnable against a real ingest:
 `TELEMETRY_DEV_API_KEY=td_live_... uv run examples/quickstart.py`.
+
+## License
+
+MIT. See [LICENSE](https://github.com/telemetry-dev/telemetry/blob/main/sdks/python/LICENSE).

{telemetry_dev-0.2.8 → telemetry_dev-0.2.10}/README.md

@@ -4,6 +4,8 @@ telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and m
 ergonomic functions over OTel spans (`gen_ai.*` semantic conventions), exported as OTLP
 protobuf to the telemetry.dev ingest.
 
+Docs: https://telemetry.dev/docs/sdk/python
+
 ## Install
 
 ```sh
@@ -76,6 +78,7 @@ later `init()` generates a new ID. It is not persisted across processes.
 | `@observe` / `@observe(name=, type=, capture_input=, capture_output=, attributes=)` | Wrap a sync/async function (or generator) in a span. Arguments become `input` (param-name dict, `self`/`cls` dropped), the return value becomes `output`, exceptions are captured and re-raised. |
 | `start_span(name, *, type="span", ...) -> SpanHandle` | Start a span. `with` activates it in the current context; without `with` it is a detached handle you must `.end()`. |
 | `SpanHandle.update(**fields)` / `.end(**fields, end_time=)` / `.record_output_chunk(timestamp_ms=None)` / `.traceparent()` | Update attributes, end, record arrival of a non-empty output chunk, or read the W3C traceparent. |
+| `SpanHandle.serialize_content(value, key) -> str \| None` | Prepare content an integration writes outside `input` and `output`, such as an error message or a raw attribute, the way `input` and `output` are prepared: the configured `mask` with `key`, JSON serialization (strings pass through), then truncation to `max_attribute_length`. Returns `None` when the mask raises (reported through `on_error`) or the value cannot be serialized; write nothing then. Does not check `capture_input` / `capture_output`. Integrations that support older cores should treat a missing method as a configured mask. |
 | `update_current_span(**fields)` | Apply the update field set to the currently active span (no-op without one). |
 | `propagate_attributes(*, user_id=, session_id=, metadata=)` | Context manager stamping `user.id` / `gen_ai.conversation.id` / `td.metadata.*` on every span and log record started inside (threads/asyncio included via contextvars). |
 | `log(message, *, level="info", event_name=None, attributes=None)` | Emit an OTLP log record to `/v1/logs`, correlated with the current trace. Levels: `debug`/`info`/`warn`/`error` (`"warning"` is accepted as an alias of `warn`). |
@@ -130,11 +133,12 @@ the core SDK with provider integrations to enable the new metric.
 | --- | --- | --- |
 | `api_key`, `base_url`, `environment`, `service_name` | env vars | Connection + resource settings. |
 | `enabled` | `True` | `False` = hard kill switch (tests). |
+| `session_mode` | `"explicit"` | `"process"` groups otherwise uncorrelated spans and logs under one generated session ID per `init()` (see [Environment variables](#environment-variables)). Other values call `on_error` and install a disabled client. |
 | `register_global` | `False` | Also register the tracer provider globally. Applies a default export filter (only `telemetry_dev`-scoped spans are exported); pass `span_filter=lambda s: True` to export everything. |
 | `export_mode` | `"batched"` | `"immediate"` exports synchronously per span/log (serverless). |
 | `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. |
+| `mask` | `None` | `Callable[[Any, MaskContext], Any]` redaction hook, runs before JSON serialization on input/output/log messages and `SpanHandle.serialize_content` (`MaskContext.key` is the attribute being written). Not applied to correlation identifiers. |
 | `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. |
@@ -148,6 +152,11 @@ still record non-content metadata such as response IDs and models, finish reason
 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.
 
+`mask` receives input and output content, system instructions, log messages, and content that
+integrations pass to `SpanHandle.serialize_content`. `MaskContext.key` names the attribute being
+written. It does not receive span or propagated `metadata`, raw `attributes`, log attributes, or
+exception messages and stack traces; redact those separately.
+
 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.
@@ -228,6 +237,68 @@ safe to attach unconditionally, with only a debug log. Auto-metrics are on by de
 GenAI spans, use the `service_name` / `environment` resource settings above, and are skipped
 without an API key.
 
+### Native Claude SDK spans
+
+The Python `anthropic` SDK 1.14.0 and later emits OpenTelemetry spans natively. The Claude SDK uses the global tracer provider of the application.
+To send these spans to telemetry.dev, register a global tracer provider with `TelemetrySpanProcessor`:
+
+```sh
+pip install telemetry-dev "anthropic>=1.14.0"
+```
+
+```python
+from anthropic import Anthropic
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from telemetry_dev.otel import TelemetrySpanProcessor
+
+provider = TracerProvider()
+provider.add_span_processor(TelemetrySpanProcessor())
+trace.set_tracer_provider(provider)
+
+client = Anthropic()
+client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=256,
+    messages=[{"role": "user", "content": "Say hello."}],
+)
+
+provider.shutdown()
+```
+
+If you use `telemetry_dev.init(register_global=True)`, also pass `span_filter=lambda span: True`. The default filter of that mode exports only the spans of this SDK.
+
+By default, the spans contain metadata only. To also send prompts and responses, set `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content`. The client reads this variable one time, when you make the client.
+
+Do not use the native spans and `telemetry-dev-anthropic` together. If you use the two, each request has two spans.
+
+You can also send the native spans without this package. Use an OTLP/HTTP protobuf exporter:
+
+```sh
+pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
+```
+
+```python
+import os
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+exporter = OTLPSpanExporter(
+    endpoint="https://ingest.telemetry.dev/v1/traces",
+    headers={"Authorization": f"Bearer {os.environ['TELEMETRY_DEV_API_KEY']}"},
+)
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(exporter))
+trace.set_tracer_provider(provider)
+```
+
+The Claude API can also send server-side spans to telemetry.dev through a Console destination. Set the endpoint to `https://ingest.telemetry.dev`. Set the `Authorization` header to `Bearer <telemetry.dev API key>`. For more information, refer to [Claude Platform](https://telemetry.dev/docs/integrations/claude-platform).
+
+When the SDK and the Claude API send the spans of a request to the same telemetry.dev project, telemetry.dev counts the tokens of the request one time, from the API span. The SDK span stays in the trace with no tokens. telemetry.dev matches the two spans by the request ID or the response ID, so the API span does not have to be a child of the SDK span. If the Console destination uses an API key that is scoped to one environment, its API spans take over only the SDK spans of that environment.
+
 ## Limitations
 
 - `register_global=True` cannot be undone on `shutdown()`: OpenTelemetry Python has no public
@@ -250,3 +321,7 @@ uv build                # build wheel + sdist
 
 `examples/quickstart.py` is runnable against a real ingest:
 `TELEMETRY_DEV_API_KEY=td_live_... uv run examples/quickstart.py`.
+
+## License
+
+MIT. See [LICENSE](https://github.com/telemetry-dev/telemetry/blob/main/sdks/python/LICENSE).

{telemetry_dev-0.2.8 → telemetry_dev-0.2.10}/pyproject.toml

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

{telemetry_dev-0.2.8 → telemetry_dev-0.2.10}/pyproject.toml.orig

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

{telemetry_dev-0.2.8 → telemetry_dev-0.2.10}/src/telemetry_dev/_capture.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+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.

{telemetry_dev-0.2.8 → telemetry_dev-0.2.10}/src/telemetry_dev/_serialize.py

@@ -66,11 +66,10 @@ def serialize_content(
             report_error(on_error, f"mask hook raised for attribute '{key}'", exc)
             return None
     try:
-        text = stringify(value)
+        return truncate(stringify(value), max_len)
     except BaseException as exc:
         report_error(on_error, f"failed to serialize attribute '{key}'", exc)
         return None
-    return truncate(text, max_len)
 
 
 def coerce_attr_value(

{telemetry_dev-0.2.8 → telemetry_dev-0.2.10}/src/telemetry_dev/_spans.py

@@ -396,6 +396,19 @@ class SpanHandle:
         if self._client is not None:
             self._client.report("provider instrumentation failed", cause)
 
+    def serialize_content(self, value: Any, key: str) -> str | None:
+        """Prepare content written outside ``input`` and ``output`` the way those are prepared.
+
+        Runs the configured mask with ``key`` (the attribute the result is written to), JSON
+        serialization (strings pass through), then truncation to ``max_attribute_length``.
+        Returns None when the mask raises (reported to ``on_error``) or the value cannot be
+        serialized. Capture flags are not checked. Cores that predate this method lack it;
+        treat a missing method as masked.
+        """
+        if self._client is None:
+            return None
+        return self._client.serialize(value, key)
+
     def _recording(self) -> bool:
         return (
             self._client is not None