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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.9
+Version: 0.2.11
 Summary: telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics
 Keywords: telemetry,opentelemetry,llm,genai,tracing,observability
 Author: telemetry.dev
@@ -17,6 +17,7 @@ Classifier: Typing :: Typed
 Requires-Dist: opentelemetry-api>=1.39.0,<2
 Requires-Dist: opentelemetry-sdk>=1.39.0,<2
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.0,<2
+Requires-Dist: rfc8785>=0.1.4
 Requires-Python: >=3.10
 Project-URL: Homepage, https://telemetry.dev
 Project-URL: Repository, https://github.com/telemetry-dev/telemetry
@@ -28,6 +29,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 +103,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`). |
@@ -148,29 +152,48 @@ the core SDK with provider integrations to enable the new metric.
 `SpanContext`), `start_time`, and per-call `capture_input` / `capture_output` overrides;
 `end()` additionally accepts `end_time`.
 
+Core SDK error recording keeps failure status, error type, and an exception event. It includes
+`exception.message` and `exception.stacktrace` only when both effective `capture_input` and
+`capture_output` are true, including per-span overrides: exceptions can echo either inputs or
+outputs. The policy is per span: when an error propagates to an enclosing span whose capture is on,
+that span records its message and stack. Included fields pass through `mask` with their exception
+attribute keys, then serialization and truncation. A truncated `exception.stacktrace` keeps its
+end, where Python normally puts the innermost frame and the exception line. Mask and serialization failures drop the affected field and report generic errors
+to `on_error` and SDK diagnostics without the original message, traceback, or exception chain.
+The original application error is raised unchanged. These controls do not scrub error type names,
+metadata, identifiers, resource attributes, or events written directly through raw OpenTelemetry APIs.
+
 ### init() options
 
 | Option | Default | Purpose |
 | --- | --- | --- |
 | `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. |
-| `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. |
+| `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. A series of failed exports, for example during an ingest outage, is one report to `on_error` and the `telemetry_dev` logger. After an export reaches the ingest, the next failure is a new report. |
 | `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.
+and error types. 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;
+redact those separately when needed.
+
+`mask` receives input and output content, system instructions, log messages, captured exception
+messages and stack traces, 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`, or log attributes;
+redact those separately. Log masking is independent of span capture flags.
 
 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.
@@ -244,7 +267,7 @@ from telemetry_dev import TelemetrySpanProcessor
 | `metrics` | `True` | Auto-record GenAI duration/token histograms for exported spans when an API key is available. |
 | `service_name` | `OTEL_SERVICE_NAME` or `unknown_service` | `service.name` on the metrics resource. |
 | `environment` | `TELEMETRY_DEV_ENVIRONMENT` or `production` | `deployment.environment.name` on the metrics resource. |
-| `on_error` | `None` | Receives internal processor errors; errors are never raised into your code. |
+| `on_error` | `None` | Receives export errors of the telemetry.dev exporters and internal processor errors; errors are never raised into your code. A series of failed exports is one report. After an export reaches the ingest, the next failure is a new report. |
 | `span_exporter` | `None` | Advanced/test seam replacing the telemetry.dev OTLP trace exporter. |
 
 Without an API key and without `span_exporter`, `TelemetrySpanProcessor()` is an inert no-op:
@@ -252,6 +275,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 +359,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.9 → telemetry_dev-0.2.11}/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`). |
@@ -124,29 +127,48 @@ the core SDK with provider integrations to enable the new metric.
 `SpanContext`), `start_time`, and per-call `capture_input` / `capture_output` overrides;
 `end()` additionally accepts `end_time`.
 
+Core SDK error recording keeps failure status, error type, and an exception event. It includes
+`exception.message` and `exception.stacktrace` only when both effective `capture_input` and
+`capture_output` are true, including per-span overrides: exceptions can echo either inputs or
+outputs. The policy is per span: when an error propagates to an enclosing span whose capture is on,
+that span records its message and stack. Included fields pass through `mask` with their exception
+attribute keys, then serialization and truncation. A truncated `exception.stacktrace` keeps its
+end, where Python normally puts the innermost frame and the exception line. Mask and serialization failures drop the affected field and report generic errors
+to `on_error` and SDK diagnostics without the original message, traceback, or exception chain.
+The original application error is raised unchanged. These controls do not scrub error type names,
+metadata, identifiers, resource attributes, or events written directly through raw OpenTelemetry APIs.
+
 ### init() options
 
 | Option | Default | Purpose |
 | --- | --- | --- |
 | `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. |
-| `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. |
+| `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. A series of failed exports, for example during an ingest outage, is one report to `on_error` and the `telemetry_dev` logger. After an export reaches the ingest, the next failure is a new report. |
 | `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.
+and error types. 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;
+redact those separately when needed.
+
+`mask` receives input and output content, system instructions, log messages, captured exception
+messages and stack traces, 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`, or log attributes;
+redact those separately. Log masking is independent of span capture flags.
 
 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.
@@ -220,7 +242,7 @@ from telemetry_dev import TelemetrySpanProcessor
 | `metrics` | `True` | Auto-record GenAI duration/token histograms for exported spans when an API key is available. |
 | `service_name` | `OTEL_SERVICE_NAME` or `unknown_service` | `service.name` on the metrics resource. |
 | `environment` | `TELEMETRY_DEV_ENVIRONMENT` or `production` | `deployment.environment.name` on the metrics resource. |
-| `on_error` | `None` | Receives internal processor errors; errors are never raised into your code. |
+| `on_error` | `None` | Receives export errors of the telemetry.dev exporters and internal processor errors; errors are never raised into your code. A series of failed exports is one report. After an export reaches the ingest, the next failure is a new report. |
 | `span_exporter` | `None` | Advanced/test seam replacing the telemetry.dev OTLP trace exporter. |
 
 Without an API key and without `span_exporter`, `TelemetrySpanProcessor()` is an inert no-op:
@@ -228,6 +250,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 +334,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.9 → telemetry_dev-0.2.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.9"
+version = "0.2.11"
 description = "telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics"
 readme = "README.md"
 license = "MIT"
@@ -28,6 +28,7 @@ dependencies = [
     "opentelemetry-api>=1.39.0,<2",
     "opentelemetry-sdk>=1.39.0,<2",
     "opentelemetry-exporter-otlp-proto-http>=1.39.0,<2",
+    "rfc8785>=0.1.4",
 ]
 
 [[project.authors]]

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

@@ -1,6 +1,6 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.9"
+version = "0.2.11"
 description = "telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics"
 readme = "README.md"
 license = "MIT"
@@ -22,6 +22,7 @@ dependencies = [
   "opentelemetry-api>=1.39.0,<2",
   "opentelemetry-sdk>=1.39.0,<2",
   "opentelemetry-exporter-otlp-proto-http>=1.39.0,<2",
+  "rfc8785>=0.1.4",
 ]
 
 [project.urls]

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

@@ -15,7 +15,6 @@ from opentelemetry.sdk._logs import LoggerProvider
 from opentelemetry.sdk._logs.export import (
     BatchLogRecordProcessor,
     LogRecordExporter,
-    LogRecordExportResult,
     SimpleLogRecordProcessor,
 )
 from opentelemetry.sdk.metrics import Histogram, MeterProvider
@@ -26,7 +25,7 @@ from opentelemetry.sdk.metrics.export import (
 )
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import ReadableSpan, SpanLimits, TracerProvider
-from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+from opentelemetry.sdk.trace.export import SpanExporter
 from opentelemetry.sdk.trace.sampling import Sampler
 from opentelemetry.trace import Tracer
 
@@ -41,6 +40,7 @@ from ._config import (
     resolve_config,
 )
 from ._context import SessionSampler
+from ._export import ExportFailures, ReportingLogExporter, ReportingSpanExporter
 from ._metrics import (
     GuardedOTLPMetricExporter,
     MetricsRecorder,
@@ -60,68 +60,6 @@ def _default_scope_filter(span: ReadableSpan) -> bool:
     return scope is not None and scope.name == SCOPE_NAME
 
 
-class _ReportingSpanExporter(SpanExporter):
-    """Surfaces transport failures to on_error (TS parity: exporters route errors to onError,
-    the stock OTLP exporter only logs them)."""
-
-    def __init__(
-        self, inner: SpanExporter, on_error: Callable[[BaseException], None] | None
-    ) -> None:
-        self._inner = inner
-        self._on_error = on_error
-
-    def export(self, spans: Any) -> SpanExportResult:
-        try:
-            result = self._inner.export(spans)
-        except BaseException as exc:
-            report_error(self._on_error, "span export failed", exc)
-            return SpanExportResult.FAILURE
-        if result is SpanExportResult.FAILURE:
-            report_error(
-                self._on_error,
-                "span export failed",
-                RuntimeError("OTLP span export failed (check the API key and ingest URL)"),
-            )
-        return result
-
-    def force_flush(self, timeout_millis: int = 30000) -> bool:
-        return self._inner.force_flush(timeout_millis)
-
-    def shutdown(self) -> None:
-        self._inner.shutdown()
-
-
-class _ReportingLogExporter(LogRecordExporter):
-    """Log-exporter twin of _ReportingSpanExporter."""
-
-    def __init__(
-        self, inner: LogRecordExporter, on_error: Callable[[BaseException], None] | None
-    ) -> None:
-        self._inner = inner
-        self._on_error = on_error
-
-    def export(self, batch: Any) -> LogRecordExportResult:
-        try:
-            result = self._inner.export(batch)
-        except BaseException as exc:
-            report_error(self._on_error, "log export failed", exc)
-            return LogRecordExportResult.FAILURE
-        if result is LogRecordExportResult.FAILURE:
-            report_error(
-                self._on_error,
-                "log export failed",
-                RuntimeError("OTLP log export failed (check the API key and ingest URL)"),
-            )
-        return result
-
-    def force_flush(self, timeout_millis: int = 30000) -> bool:
-        inner_flush = getattr(self._inner, "force_flush", None)
-        return inner_flush(timeout_millis) if inner_flush is not None else True
-
-    def shutdown(self) -> None:
-        self._inner.shutdown()
-
-
 class Client:
     """Holds the telemetry pipelines for one init() call. Obtain via telemetry_dev.init()."""
 
@@ -195,6 +133,7 @@ class Client:
             ),
         )
         self._tracer_provider.sampler = SessionSampler(self._tracer_provider.sampler)
+        failures = ExportFailures(on_error)
 
         # Without an api key (enabled via a test seam), never construct real network
         # exporters — they would POST to the ingest with a bogus Authorization header.
@@ -206,7 +145,7 @@ class Client:
                 compression=Compression.Gzip,
                 timeout=timeout,
                 preferred_temporality={Histogram: AggregationTemporality.DELTA},
-                on_error=on_error,
+                failures=failures,
             )
             metric_exporter.output_chunks = self._output_chunks
             metric_reader = PeriodicExportingMetricReader(
@@ -221,14 +160,14 @@ class Client:
             )
 
         if span_exporter is None:
-            span_exporter = _ReportingSpanExporter(
+            span_exporter = ReportingSpanExporter(
                 OTLPSpanExporter(
                     endpoint=f"{config.base_url}/v1/traces",
                     headers=headers,
                     compression=Compression.Gzip,
                     timeout=timeout,
                 ),
-                on_error,
+                failures,
             )
         if span_filter is None and register_global:
             span_filter = _default_scope_filter
@@ -243,14 +182,14 @@ class Client:
         self.tracer = self._tracer_provider.get_tracer(SCOPE_NAME, SDK_VERSION)
 
         if log_exporter is None and config.api_key is not None:
-            log_exporter = _ReportingLogExporter(
+            log_exporter = ReportingLogExporter(
                 OTLPLogExporter(
                     endpoint=f"{config.base_url}/v1/logs",
                     headers=headers,
                     compression=Compression.Gzip,
                     timeout=timeout,
                 ),
-                on_error,
+                failures,
             )
         if log_exporter is not None:
             self._logger_provider = LoggerProvider(resource=resource, shutdown_on_exit=False)
@@ -277,13 +216,14 @@ class Client:
     def report(self, message: str, exc: BaseException) -> None:
         report_error(self.on_error, message, exc)
 
-    def serialize(self, value: Any, key: str) -> str | None:
+    def serialize(self, value: Any, key: str, *, keep_end: bool = False) -> str | None:
         return serialize_content(
             value,
             key=key,
             mask=self.mask,
             max_len=self.max_attribute_length,
             on_error=self.on_error,
+            keep_end=keep_end,
         )
 
     def flush(self, timeout_s: float = 10.0) -> None:

{telemetry_dev-0.2.9 → telemetry_dev-0.2.11}/src/telemetry_dev/_config.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import logging
 import os
 import re
+import traceback
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Literal
@@ -74,9 +75,12 @@ def report_error(
     exc: BaseException,
 ) -> None:
     """Route an internal SDK error to the on_error hook + leveled logger; never raises."""
+    # Snapshot before callbacks can re-raise exc and attach application exception chains.
+    if logger.isEnabledFor(logging.ERROR):
+        trace = "".join(traceback.format_exception(exc)).rstrip()
+        logger.error("telemetry-dev: %s\n%s", message, trace)
     if on_error is not None:
         try:
             on_error(exc)
         except BaseException:
-            logger.debug("telemetry-dev on_error hook raised", exc_info=True)
-    logger.error("telemetry-dev: %s", message, exc_info=exc)
+            logger.debug("telemetry-dev on_error hook raised")

telemetry_dev-0.2.11/src/telemetry_dev/_export.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from opentelemetry.sdk._logs.export import LogRecordExporter, LogRecordExportResult
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+
+from ._config import report_error
+
+
+class ExportFailures:
+    """Reports the first failed export of a series to on_error and the SDK logger.
+
+    The series stops when an export reaches the ingest, and the next failed export starts a new
+    series. During an outage, each batch is a failed export, and one report for each batch is too
+    many. The exporters of one client or TelemetrySpanProcessor use one instance, so an outage
+    that stops traces, logs, and metrics is one report. Exporters run on background threads, thus
+    report() and clear() hold a lock.
+    """
+
+    def __init__(self, on_error: Callable[[BaseException], None] | None) -> None:
+        self._on_error = on_error
+        self._lock = threading.Lock()
+        self._reported = False
+
+    def report(self, message: str, exc: BaseException) -> None:
+        with self._lock:
+            if self._reported:
+                return
+            self._reported = True
+        # report_error runs outside the lock. Thus a slow on_error does not stop other exporters,
+        # and an on_error that sends telemetry does not deadlock.
+        report_error(self._on_error, message, exc)
+
+    def clear(self) -> None:
+        """Records that an export reached the ingest, so that report() sends the next failure."""
+        with self._lock:
+            self._reported = False
+
+
+class ReportingSpanExporter(SpanExporter):
+    """Reports export failures through its ExportFailures (TS parity). The OTLP exporter of
+    OpenTelemetry only logs them."""
+
+    def __init__(self, inner: SpanExporter, failures: ExportFailures) -> None:
+        self._inner = inner
+        self._failures = failures
+
+    def export(self, spans: Any) -> SpanExportResult:
+        try:
+            result = self._inner.export(spans)
+        except BaseException as exc:
+            self._failures.report("span export failed", exc)
+            return SpanExportResult.FAILURE
+        if result is SpanExportResult.FAILURE:
+            self._failures.report(
+                "span export failed",
+                RuntimeError("OTLP span export failed (check the API key and ingest URL)"),
+            )
+        else:
+            self._failures.clear()
+        return result
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return self._inner.force_flush(timeout_millis)
+
+    def shutdown(self) -> None:
+        self._inner.shutdown()
+
+
+class ReportingLogExporter(LogRecordExporter):
+    """Log-exporter twin of ReportingSpanExporter."""
+
+    def __init__(self, inner: LogRecordExporter, failures: ExportFailures) -> None:
+        self._inner = inner
+        self._failures = failures
+
+    def export(self, batch: Any) -> LogRecordExportResult:
+        try:
+            result = self._inner.export(batch)
+        except BaseException as exc:
+            self._failures.report("log export failed", exc)
+            return LogRecordExportResult.FAILURE
+        if result is LogRecordExportResult.FAILURE:
+            self._failures.report(
+                "log export failed",
+                RuntimeError("OTLP log export failed (check the API key and ingest URL)"),
+            )
+        else:
+            self._failures.clear()
+        return result
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        inner_flush = getattr(self._inner, "force_flush", None)
+        return inner_flush(timeout_millis) if inner_flush is not None else True
+
+    def shutdown(self) -> None:
+        self._inner.shutdown()

{telemetry_dev-0.2.9 → telemetry_dev-0.2.11}/src/telemetry_dev/_metrics.py

@@ -27,6 +27,7 @@ from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.trace import INVALID_SPAN_CONTEXT, NonRecordingSpan, set_span_in_context
 
 from ._config import report_error
+from ._export import ExportFailures
 from ._semconv import (
     ATTR_ERROR_TYPE,
     ATTR_TIME_TO_FIRST_CHUNK,
@@ -72,8 +73,7 @@ class _ChunkAggregate:
 
 
 class OutputChunkAggregation:
-    def __init__(self, max_attribute_sets: int = _MAX_CHUNK_ATTRIBUTE_SETS) -> None:
-        self._max_attribute_sets = max_attribute_sets
+    def __init__(self) -> None:
         self._values: dict[tuple[tuple[str, Any], ...], _ChunkAggregate] = {}
         self._lock = threading.Lock()
         self._collection_start = time.time_ns()
@@ -85,7 +85,7 @@ class OutputChunkAggregation:
     ) -> None:
         key = tuple(sorted(attributes.items()))
         with self._lock:
-            if key not in self._values and len(self._values) >= self._max_attribute_sets - 1:
+            if key not in self._values and len(self._values) >= _MAX_CHUNK_ATTRIBUTE_SETS - 1:
                 key = (("otel.metric.overflow", True),)
             count, total, minimum, maximum, buckets = aggregate
             existing = self._values.get(key)
@@ -167,16 +167,17 @@ def _has_data_points(metrics_data: MetricsData) -> bool:
 
 class GuardedOTLPMetricExporter(OTLPMetricExporter):
     """OTLP metric exporter that skips POSTs for collections with zero data points
-    (mirrors the TS emitter's empty-datapoint guard) and surfaces failures to on_error."""
+    (mirrors the TS emitter's empty-datapoint guard) and reports failures through its
+    ExportFailures."""
 
     def __init__(
         self,
         *args: Any,
-        on_error: Callable[[BaseException], None] | None = None,
+        failures: ExportFailures,
         **kwargs: Any,
     ) -> None:
         super().__init__(*args, **kwargs)  # pyright: ignore[reportUnknownMemberType]
-        self._td_on_error = on_error
+        self._td_failures = failures
         self.output_chunks: OutputChunkAggregation | None = None
 
     def export(
@@ -188,20 +189,22 @@ class GuardedOTLPMetricExporter(OTLPMetricExporter):
         if self.output_chunks is not None:
             metrics_data = _with_output_chunks(metrics_data, self.output_chunks)
         if not _has_data_points(metrics_data):
+            # No request reaches the ingest, so a series of failed exports continues.
             return MetricExportResult.SUCCESS
         try:
             result = super().export(  # pyright: ignore[reportUnknownMemberType]
                 metrics_data, timeout_millis=timeout_millis, **kwargs
             )
         except BaseException as exc:
-            report_error(self._td_on_error, "metric export failed", exc)
+            self._td_failures.report("metric export failed", exc)
             return MetricExportResult.FAILURE
         if result is MetricExportResult.FAILURE:
-            report_error(
-                self._td_on_error,
+            self._td_failures.report(
                 "metric export failed",
                 RuntimeError("OTLP metric export failed (check the API key and ingest URL)"),
             )
+        else:
+            self._td_failures.clear()
         return result
 
 

telemetry_dev-0.2.11/src/telemetry_dev/_serialize.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, cast
+
+import rfc8785
+
+from ._config import report_error
+
+TRUNCATION_MARKER = "...[truncated]"
+DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536
+_MAX_SAFE_INTEGER = 2**53 - 1
+_MAX_ARRAY_INDEX = 2**32 - 2
+_SURROGATES = re.compile("[\ud800-\udfff]")
+
+AttributeValue = (
+    str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]
+)
+
+
+@dataclass(frozen=True)
+class MaskContext:
+    key: str
+
+
+Mask = Callable[[Any, MaskContext], Any]
+
+
+def truncate(text: str, max_len: int, *, keep_end: bool = False) -> str:
+    """Cap ``text`` at ``max_len`` UTF-16 units, marking the cut.
+
+    ``keep_end`` keeps the tail and puts the marker first, for text whose most useful part
+    comes last.
+    """
+    # Count UTF-16 units like JavaScript, but back off at a split surrogate pair
+    # rather than emitting the lone surrogate that String.slice would retain.
+    if len(text) * 2 <= max_len:
+        return text
+    encoded = text.encode("utf-16-le")
+    if len(encoded) <= max_len * 2:
+        return text
+    if max_len < len(TRUNCATION_MARKER):
+        return TRUNCATION_MARKER[: max(max_len, 0)]
+    kept = (max_len - len(TRUNCATION_MARKER)) * 2
+    if keep_end:
+        tail = encoded[len(encoded) - kept :]
+        try:
+            return TRUNCATION_MARKER + tail.decode("utf-16-le")
+        except UnicodeDecodeError:
+            return TRUNCATION_MARKER + tail[2:].decode("utf-16-le")
+    head = encoded[:kept]
+    try:
+        return head.decode("utf-16-le") + TRUNCATION_MARKER
+    except UnicodeDecodeError:
+        return head[:-2].decode("utf-16-le") + TRUNCATION_MARKER
+
+
+def _json_number(value: int | float) -> str:
+    if isinstance(value, int) and -_MAX_SAFE_INTEGER <= value <= _MAX_SAFE_INTEGER:
+        # int subclasses such as IntEnum on Python 3.10 may override __str__ with non-JSON text.
+        return int.__repr__(value)
+    try:
+        number = float(value)
+    except OverflowError:
+        return "null"
+    return rfc8785.dumps(number).decode("ascii") if math.isfinite(number) else "null"
+
+
+def _json_string(value: str) -> str:
+    if _SURROGATES.search(value):
+        value = value.encode("utf-16-le", "surrogatepass").decode("utf-16-le", "surrogatepass")
+        return _SURROGATES.sub(
+            lambda match: f"\\u{ord(match[0]):04x}", json.dumps(value, ensure_ascii=False)
+        )
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _json_key_order(key: str) -> tuple[int, int]:
+    if key.isascii() and key.isdigit() and len(key) <= 10:
+        index = int(key)
+        if index <= _MAX_ARRAY_INDEX and str(index) == key:
+            return 0, index
+    return 1, 0
+
+
+def json_dumps(value: Any, *, default: Callable[[Any], Any] | None = repr) -> str:
+    """JSON.stringify spelling and key order for JSON values; default handles Python-only values."""
+    active: set[int] = set()
+    chunks: list[str] = []
+
+    def encode(item: Any) -> None:
+        if item is None:
+            chunks.append("null")
+            return
+        if isinstance(item, bool):
+            chunks.append("true" if item else "false")
+            return
+        if isinstance(item, str):
+            chunks.append(_json_string(item))
+            return
+        if isinstance(item, int | float):
+            chunks.append(_json_number(item))
+            return
+        identity = id(item)
+        if identity in active:
+            raise ValueError("Circular reference detected")
+        active.add(identity)
+        try:
+            if isinstance(item, dict):
+                properties: dict[str, Any] = {}
+                for key, child in cast("dict[Any, Any]", item).items():
+                    if not isinstance(key, str):
+                        if key is None:
+                            key = "null"
+                        elif isinstance(key, bool):
+                            key = "true" if key else "false"
+                        elif isinstance(key, float) and not math.isfinite(key):
+                            key = json.dumps(key)
+                        elif isinstance(key, int | float):
+                            key = _json_number(key)
+                        else:
+                            raise TypeError("JSON object keys must be strings or scalars")
+                    if _SURROGATES.search(key):
+                        key = key.encode("utf-16-le", "surrogatepass").decode(
+                            "utf-16-le", "surrogatepass"
+                        )
+                    properties[key] = child
+                chunks.append("{")
+                for index, key in enumerate(sorted(properties, key=_json_key_order)):
+                    if index:
+                        chunks.append(",")
+                    chunks.extend((_json_string(key), ":"))
+                    encode(properties[key])
+                chunks.append("}")
+            elif isinstance(item, list | tuple):
+                chunks.append("[")
+                for index, child in enumerate(cast("list[Any] | tuple[Any, ...]", item)):
+                    if index:
+                        chunks.append(",")
+                    encode(child)
+                chunks.append("]")
+            elif default is not None:
+                encode(default(item))
+            else:
+                raise TypeError(f"Object of type {type(item).__name__} is not JSON serializable")
+        finally:
+            active.remove(identity)
+
+    encode(value)
+    return "".join(chunks)
+
+
+def stringify(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return json_dumps(value)
+
+
+def serialize_content(
+    value: Any,
+    *,
+    key: str,
+    mask: Mask | None,
+    max_len: int,
+    on_error: Callable[[BaseException], None] | None = None,
+    keep_end: bool = False,
+) -> str | None:
+    """The single content funnel: mask -> JSON stringify -> truncate.
+
+    Returns None (content dropped, matching the TypeScript SDK) when the mask hook raises
+    or the value cannot be stringified. ``keep_end`` is passed to ``truncate``.
+    """
+    if mask is not None:
+        try:
+            value = mask(value, MaskContext(key=key))
+        except BaseException:
+            # Raised hook errors can retain unmasked values and the application exception chain.
+            message = "mask hook raised; content dropped"
+            report_error(on_error, message, RuntimeError(message))
+            return None
+    try:
+        return truncate(stringify(value), max_len, keep_end=keep_end)
+    except BaseException:
+        message = "failed to serialize attribute; content dropped"
+        report_error(on_error, message, ValueError(message))
+        return None
+
+
+def coerce_attr_value(
+    value: Any,
+    *,
+    max_len: int = DEFAULT_MAX_ATTRIBUTE_LENGTH,
+    key: str | None = None,
+    on_error: Callable[[BaseException], None] | None = None,
+) -> AttributeValue | None:
+    """Pass scalars and homogeneous scalar sequences through; JSON-stringify everything else."""
+    try:
+        if isinstance(value, bool | int | float):
+            return value
+        if isinstance(value, str):
+            return truncate(value, max_len)
+        if isinstance(value, Sequence) and not isinstance(value, Mapping):
+            items: list[Any] = list(cast("Sequence[Any]", value))
+            if items and all(isinstance(item, str) for item in items):
+                return [truncate(item, max_len) for item in items]
+            if items and all(isinstance(item, bool) for item in items):
+                return items
+            if items and all(
+                isinstance(item, int | float) and not isinstance(item, bool) for item in items
+            ):
+                return items
+        return truncate(stringify(value), max_len)
+    except BaseException:
+        message = "failed to serialize attribute; content dropped"
+        report_error(on_error, message, ValueError(message))
+        return None

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

@@ -147,20 +147,32 @@ def _to_ns(value: TimeInput) -> int | None:
     return int(value)
 
 
-def _record_error_on_span(span: Span, error: BaseException) -> None:
+def _record_error_on_span(
+    client: Client, span: Span, state: _SpanState, error: BaseException
+) -> None:
     error_type = type(error).__name__
-    stacktrace = "".join(traceback.format_exception(type(error), error, error.__traceback__))
     span.set_attribute(ATTR_ERROR_TYPE, error_type)
-    span.add_event(
-        "exception",
-        {
-            "exception.type": error_type,
-            "exception.message": str(error),
-            "exception.stacktrace": stacktrace,
-            "log.severity_number": SEVERITY["error"],
-        },
-    )
     span.set_status(Status(StatusCode.ERROR))
+    attributes: dict[str, otel_types.AttributeValue] = {
+        "exception.type": error_type,
+        "log.severity_number": SEVERITY["error"],
+    }
+    # Exceptions can echo either inputs or outputs; both must allow content capture.
+    if state.capture_input and state.capture_output:
+        # A Python traceback ends with the innermost frame and the exception line, so a
+        # truncated one keeps its end.
+        for key, value, keep_end in (
+            ("exception.message", str(error), False),
+            (
+                "exception.stacktrace",
+                "".join(traceback.format_exception(type(error), error, error.__traceback__)),
+                True,
+            ),
+        ):
+            serialized = client.serialize(value, key, keep_end=keep_end)
+            if serialized is not None:
+                attributes[key] = serialized
+    span.add_event("exception", attributes)
 
 
 def _metadata_attrs(
@@ -288,7 +300,7 @@ def _apply_fields(client: Client, span: Span, state: _SpanState, fields: dict[st
 
     error = fields.get("error")
     if error is not None:
-        _record_error_on_span(span, error)
+        _record_error_on_span(client, span, state, error)
 
 
 def _collect_fields(
@@ -396,6 +408,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

{telemetry_dev-0.2.9 → telemetry_dev-0.2.11}/src/telemetry_dev/otel.py

@@ -22,6 +22,7 @@ from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
 from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
 
 from ._config import SDK_VERSION, logger, report_error, resolve_config
+from ._export import ExportFailures, ReportingSpanExporter
 from ._metrics import GuardedOTLPMetricExporter, MetricsRecorder, sdk_meter_provider
 from ._processor import ExportMode, StampingSpanProcessor
 from ._semconv import SCOPE_NAME
@@ -104,6 +105,9 @@ class TelemetrySpanProcessor(SpanProcessor):
             service_name=service_name,
         )
 
+        # The span and metric exporters use one failure state, as the exporters of a client do.
+        failures = ExportFailures(on_error)
+
         if span_exporter is None:
             span_exporter = create_telemetry_span_exporter(
                 api_key=config.api_key,
@@ -111,6 +115,7 @@ class TelemetrySpanProcessor(SpanProcessor):
             )
             if isinstance(span_exporter, _NoOpSpanExporter):
                 return
+            span_exporter = ReportingSpanExporter(span_exporter, failures)
 
         if metrics_recorder is None and metrics and config.api_key is not None:
             resource = Resource.create(
@@ -128,6 +133,7 @@ class TelemetrySpanProcessor(SpanProcessor):
                 compression=Compression.Gzip,
                 timeout=_EXPORTER_TIMEOUT_S,
                 preferred_temporality={Histogram: AggregationTemporality.DELTA},
+                failures=failures,
             )
             reader = PeriodicExportingMetricReader(
                 metric_exporter,

telemetry_dev-0.2.9/src/telemetry_dev/_serialize.py

@@ -1,103 +0,0 @@
-from __future__ import annotations
-
-import json
-from collections.abc import Callable, Mapping, Sequence
-from dataclasses import dataclass
-from typing import Any, cast
-
-from ._config import report_error
-
-TRUNCATION_MARKER = "...[truncated]"
-DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536
-
-AttributeValue = (
-    str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]
-)
-
-
-@dataclass(frozen=True)
-class MaskContext:
-    key: str
-
-
-Mask = Callable[[Any, MaskContext], Any]
-
-
-def truncate(text: str, max_len: int) -> str:
-    # The cap counts UTF-16 code units (JavaScript's String.length) so both SDKs truncate
-    # identical payloads at the same point; a slice landing mid-surrogate-pair backs off one unit.
-    if len(text) * 2 <= max_len:
-        return text
-    encoded = text.encode("utf-16-le")
-    if len(encoded) <= max_len * 2:
-        return text
-    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:
-        return head[:-2].decode("utf-16-le") + TRUNCATION_MARKER
-
-
-def stringify(value: Any) -> str:
-    if isinstance(value, str):
-        return value
-    return json.dumps(value, default=repr, ensure_ascii=False)
-
-
-def serialize_content(
-    value: Any,
-    *,
-    key: str,
-    mask: Mask | None,
-    max_len: int,
-    on_error: Callable[[BaseException], None] | None = None,
-) -> str | None:
-    """The single content funnel: mask -> JSON stringify -> truncate.
-
-    Returns None (content dropped, matching the TypeScript SDK) when the mask hook raises
-    or the value cannot be stringified.
-    """
-    if mask is not None:
-        try:
-            value = mask(value, MaskContext(key=key))
-        except BaseException as exc:
-            report_error(on_error, f"mask hook raised for attribute '{key}'", exc)
-            return None
-    try:
-        text = stringify(value)
-    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(
-    value: Any,
-    *,
-    max_len: int = DEFAULT_MAX_ATTRIBUTE_LENGTH,
-    key: str | None = None,
-    on_error: Callable[[BaseException], None] | None = None,
-) -> AttributeValue | None:
-    """Pass scalars and homogeneous scalar sequences through; JSON-stringify everything else."""
-    try:
-        if isinstance(value, bool | int | float):
-            return value
-        if isinstance(value, str):
-            return truncate(value, max_len)
-        if isinstance(value, Sequence) and not isinstance(value, Mapping):
-            items: list[Any] = list(cast("Sequence[Any]", value))
-            if items and all(isinstance(item, str) for item in items):
-                return [truncate(item, max_len) for item in items]
-            if items and all(isinstance(item, bool) for item in items):
-                return items
-            if items and all(
-                isinstance(item, int | float) and not isinstance(item, bool) for item in items
-            ):
-                return items
-        return truncate(stringify(value), max_len)
-    except BaseException as exc:
-        suffix = f" '{key}'" if key is not None else ""
-        report_error(on_error, f"failed to serialize attribute{suffix}", exc)
-        return None