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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.10
+Version: 0.2.12
 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
@@ -80,7 +81,7 @@ routed to the `on_error` hook / `telemetry_dev` logger — never raised into you
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `TELEMETRY_DEV_API_KEY` | — | Ingest key (`td_live_...`). Absent = SDK is a no-op. |
-| `TELEMETRY_DEV_BASE_URL` | `https://ingest.telemetry.dev` | Ingest base URL (trailing slashes stripped). |
+| `TELEMETRY_DEV_BASE_URL` | `https://ingest.telemetry.dev` | Base URL for telemetry export and `get_prompt` (trailing slashes stripped). |
 | `TELEMETRY_DEV_ENVIRONMENT` | `production` | Deployment environment label. |
 | `OTEL_SERVICE_NAME` | `unknown_service` | Service name on every trace. |
 | `OTEL_TRACES_SAMPLER` | `parentbased_always_on` | OTel trace sampling policy, which includes session roots. |
@@ -107,6 +108,8 @@ later `init()` generates a new ID. It is not persisted across processes.
 | `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`). |
 | `get_traceparent() -> str \| None` | W3C traceparent of the current context. |
+| `get_prompt(name, *, label=, version=, type="chat", cache_ttl_seconds=60, fallback=, api_key=, base_url=)` / `get_prompt_async(...)` | Fetch a prompt by label or version; see [Prompts](#prompts). |
+| `with_prompt(prompt)` | Context manager recording the prompt on each model call started inside. |
 | `flush(timeout_s=10.0)` / `shutdown(timeout_s=10.0)` | Force-flush / tear down traces + logs + metrics. Shutdown also runs atexit unless `disable_atexit=True`. |
 | `TelemetrySpanProcessor` / `telemetry_dev.otel.create_telemetry_span_exporter` | Bring-your-own-OTel helpers (below). |
 | `MaskContext`, `Usage`, `SpanHandle`, `Client`, `NOT_GIVEN` | Supporting types. |
@@ -151,6 +154,17 @@ 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 |
@@ -166,20 +180,22 @@ the core SDK with provider integrations to enable the new metric.
 | `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, and content that
+`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`, log attributes, or
-exception messages and stack traces; redact those separately.
+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.
@@ -187,6 +203,73 @@ For example, `init(sampler=ParentBased(TraceIdRatioBased(0.1)))` samples session
 These classes come from `opentelemetry.sdk.trace.sampling`.
 The built-in Python and TypeScript ratio samplers can select different sessions because the OTel algorithms differ.
 
+## Prompts
+
+`get_prompt` fetches a prompt that you manage in telemetry.dev. Fetch it by its label, so that you
+deploy a version when you move the label, without a change to the code:
+
+```python
+import telemetry_dev
+from openai import OpenAI
+from telemetry_dev_openai import wrap_openai
+
+telemetry_dev.init()
+client = wrap_openai(OpenAI())
+
+prompt = telemetry_dev.get_prompt("support/reply", label="production")
+messages = prompt.compile(customer_message=customer_message, tone=tone)
+
+with telemetry_dev.with_prompt(prompt):
+    response = client.chat.completions.create(
+        model=prompt.model["name"] if prompt.model else "gpt-4o", messages=messages
+    )
+
+# Pin one version, as in a test:
+pinned = telemetry_dev.get_prompt("support/reply", version=13)
+```
+
+- Without `label` and `version`, `get_prompt` fetches the `production` label. A text prompt needs
+  `type="text"`; `get_prompt` raises for a prompt of the other type.
+- `compile(variables)` or `compile(**variables)` puts the values in place of `{{name}}`. A missing
+  value or `None` becomes an empty text, and a value that is not a string becomes JSON. In a chat
+  prompt, a placeholder message becomes the list of messages in its variable. A text prompt
+  compiles to a string.
+- The prompt also has `model`, `parameters`, `tools`, and `response_format` of its version. The
+  keys inside them are the API's (`maxTokens`, `topP`, ...).
+- `get_prompt` keeps each prompt. When the copy is older than `cache_ttl_seconds` (default 60), a
+  call returns it at once and fetches a new copy in a background thread. Only a call with no copy
+  waits for a fetch, for 10 seconds at most, also when the network stops. Calls for the same
+  prompt share one fetch. `get_prompt_async` runs the same function in a worker thread.
+- If a fetch fails, `get_prompt` returns the last copy that it fetched and reports the error
+  through `on_error`. With no copy, it returns the `fallback` (`version` is `None` and
+  `is_fallback` is `True`). With no fallback, it raises `PromptError` whose `code` tells why, for
+  example `prompt_not_found`, `label_not_found`, `insufficient_scope`, `missing_api_key`, or
+  `timeout`. A response with a different status and no API error gives `http_<status>`, for
+  example `http_302` for a redirect. `get_prompt` does not send the request to the location of a
+  redirect, thus your key does not go to a different host. With no copy, the calls of the next 10
+  seconds (or the TTL, if it is shorter) get the same result without a fetch. This is the one SDK
+  function that can raise: your app cannot run without its prompt.
+- `get_prompt` uses the API key and base URL of an enabled `init()`, or `TELEMETRY_DEV_API_KEY`
+  and `TELEMETRY_DEV_BASE_URL`, or its own `api_key` and `base_url`. It reads the same host that
+  telemetry goes to, `https://ingest.telemetry.dev` by default. The key needs the read scope for
+  prompts.
+- When a label sends part of the traffic to a second version, each session keeps one version: the
+  choice uses the session id of `propagate_attributes` (or of `session_mode="process"`). Without a
+  session id, each call chooses at random.
+
+`with_prompt(prompt)` records the prompt on each model call that starts inside it:
+`td.prompt.name`, `td.prompt.version`, and `td.prompt.label` (only for a prompt fetched by label).
+When input capture is on, `td.prompt.variables` holds the JSON of the variables of the last
+`compile()` of that prompt object before `with_prompt` starts, or of the last `compile()` inside
+it, after `mask` and truncation. If threads or tasks that run at the same time share one prompt
+object, call `compile()` in `with_prompt`, or call `get_prompt` in each thread or task.
+`get_prompt` returns a new object from the cache. If you do not, a thread can record the variables
+of a different thread. Model calls are the spans of type `generation` (operations `chat`,
+`text_completion`, and `generate_content`), including the spans of the provider integrations:
+OpenAI, Anthropic, Amazon Bedrock, Google GenAI, LiteLLM, and OpenRouter. Spans from other
+OpenTelemetry tracers do not get the attributes. Messages from `compile()` that you pass to a
+model call outside `with_prompt` are not recorded.
+
 ## Auto-metrics
 
 Ended spans automatically record histograms (DELTA temporality, exported every 60s):
@@ -253,7 +336,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:

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

@@ -56,7 +56,7 @@ routed to the `on_error` hook / `telemetry_dev` logger — never raised into you
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `TELEMETRY_DEV_API_KEY` | — | Ingest key (`td_live_...`). Absent = SDK is a no-op. |
-| `TELEMETRY_DEV_BASE_URL` | `https://ingest.telemetry.dev` | Ingest base URL (trailing slashes stripped). |
+| `TELEMETRY_DEV_BASE_URL` | `https://ingest.telemetry.dev` | Base URL for telemetry export and `get_prompt` (trailing slashes stripped). |
 | `TELEMETRY_DEV_ENVIRONMENT` | `production` | Deployment environment label. |
 | `OTEL_SERVICE_NAME` | `unknown_service` | Service name on every trace. |
 | `OTEL_TRACES_SAMPLER` | `parentbased_always_on` | OTel trace sampling policy, which includes session roots. |
@@ -83,6 +83,8 @@ later `init()` generates a new ID. It is not persisted across processes.
 | `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`). |
 | `get_traceparent() -> str \| None` | W3C traceparent of the current context. |
+| `get_prompt(name, *, label=, version=, type="chat", cache_ttl_seconds=60, fallback=, api_key=, base_url=)` / `get_prompt_async(...)` | Fetch a prompt by label or version; see [Prompts](#prompts). |
+| `with_prompt(prompt)` | Context manager recording the prompt on each model call started inside. |
 | `flush(timeout_s=10.0)` / `shutdown(timeout_s=10.0)` | Force-flush / tear down traces + logs + metrics. Shutdown also runs atexit unless `disable_atexit=True`. |
 | `TelemetrySpanProcessor` / `telemetry_dev.otel.create_telemetry_span_exporter` | Bring-your-own-OTel helpers (below). |
 | `MaskContext`, `Usage`, `SpanHandle`, `Client`, `NOT_GIVEN` | Supporting types. |
@@ -127,6 +129,17 @@ 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 |
@@ -142,20 +155,22 @@ the core SDK with provider integrations to enable the new metric.
 | `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, and content that
+`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`, log attributes, or
-exception messages and stack traces; redact those separately.
+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.
@@ -163,6 +178,73 @@ For example, `init(sampler=ParentBased(TraceIdRatioBased(0.1)))` samples session
 These classes come from `opentelemetry.sdk.trace.sampling`.
 The built-in Python and TypeScript ratio samplers can select different sessions because the OTel algorithms differ.
 
+## Prompts
+
+`get_prompt` fetches a prompt that you manage in telemetry.dev. Fetch it by its label, so that you
+deploy a version when you move the label, without a change to the code:
+
+```python
+import telemetry_dev
+from openai import OpenAI
+from telemetry_dev_openai import wrap_openai
+
+telemetry_dev.init()
+client = wrap_openai(OpenAI())
+
+prompt = telemetry_dev.get_prompt("support/reply", label="production")
+messages = prompt.compile(customer_message=customer_message, tone=tone)
+
+with telemetry_dev.with_prompt(prompt):
+    response = client.chat.completions.create(
+        model=prompt.model["name"] if prompt.model else "gpt-4o", messages=messages
+    )
+
+# Pin one version, as in a test:
+pinned = telemetry_dev.get_prompt("support/reply", version=13)
+```
+
+- Without `label` and `version`, `get_prompt` fetches the `production` label. A text prompt needs
+  `type="text"`; `get_prompt` raises for a prompt of the other type.
+- `compile(variables)` or `compile(**variables)` puts the values in place of `{{name}}`. A missing
+  value or `None` becomes an empty text, and a value that is not a string becomes JSON. In a chat
+  prompt, a placeholder message becomes the list of messages in its variable. A text prompt
+  compiles to a string.
+- The prompt also has `model`, `parameters`, `tools`, and `response_format` of its version. The
+  keys inside them are the API's (`maxTokens`, `topP`, ...).
+- `get_prompt` keeps each prompt. When the copy is older than `cache_ttl_seconds` (default 60), a
+  call returns it at once and fetches a new copy in a background thread. Only a call with no copy
+  waits for a fetch, for 10 seconds at most, also when the network stops. Calls for the same
+  prompt share one fetch. `get_prompt_async` runs the same function in a worker thread.
+- If a fetch fails, `get_prompt` returns the last copy that it fetched and reports the error
+  through `on_error`. With no copy, it returns the `fallback` (`version` is `None` and
+  `is_fallback` is `True`). With no fallback, it raises `PromptError` whose `code` tells why, for
+  example `prompt_not_found`, `label_not_found`, `insufficient_scope`, `missing_api_key`, or
+  `timeout`. A response with a different status and no API error gives `http_<status>`, for
+  example `http_302` for a redirect. `get_prompt` does not send the request to the location of a
+  redirect, thus your key does not go to a different host. With no copy, the calls of the next 10
+  seconds (or the TTL, if it is shorter) get the same result without a fetch. This is the one SDK
+  function that can raise: your app cannot run without its prompt.
+- `get_prompt` uses the API key and base URL of an enabled `init()`, or `TELEMETRY_DEV_API_KEY`
+  and `TELEMETRY_DEV_BASE_URL`, or its own `api_key` and `base_url`. It reads the same host that
+  telemetry goes to, `https://ingest.telemetry.dev` by default. The key needs the read scope for
+  prompts.
+- When a label sends part of the traffic to a second version, each session keeps one version: the
+  choice uses the session id of `propagate_attributes` (or of `session_mode="process"`). Without a
+  session id, each call chooses at random.
+
+`with_prompt(prompt)` records the prompt on each model call that starts inside it:
+`td.prompt.name`, `td.prompt.version`, and `td.prompt.label` (only for a prompt fetched by label).
+When input capture is on, `td.prompt.variables` holds the JSON of the variables of the last
+`compile()` of that prompt object before `with_prompt` starts, or of the last `compile()` inside
+it, after `mask` and truncation. If threads or tasks that run at the same time share one prompt
+object, call `compile()` in `with_prompt`, or call `get_prompt` in each thread or task.
+`get_prompt` returns a new object from the cache. If you do not, a thread can record the variables
+of a different thread. Model calls are the spans of type `generation` (operations `chat`,
+`text_completion`, and `generate_content`), including the spans of the provider integrations:
+OpenAI, Anthropic, Amazon Bedrock, Google GenAI, LiteLLM, and OpenRouter. Spans from other
+OpenTelemetry tracers do not get the attributes. Messages from `compile()` that you pass to a
+model call outside `with_prompt` are not recorded.
+
 ## Auto-metrics
 
 Ended spans automatically record histograms (DELTA temporality, exported every 60s):
@@ -229,7 +311,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:

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

@@ -1,6 +1,6 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.10"
+version = "0.2.12"
 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.10 → telemetry_dev-0.2.12}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.10"
+version = "0.2.12"
 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.10 → telemetry_dev-0.2.12}/src/telemetry_dev/__init__.py

@@ -19,6 +19,16 @@ from ._config import LogLevelOption
 from ._context import get_traceparent, propagate_attributes
 from ._logs import log
 from ._observe import observe
+from ._prompts import (
+    ChatPrompt,
+    Prompt,
+    PromptError,
+    PromptModel,
+    TextPrompt,
+    get_prompt,
+    get_prompt_async,
+    with_prompt,
+)
 from ._semconv import LogLevel, SpanType
 from ._serialize import AttributeValue, Mask, MaskContext
 from ._spans import (
@@ -34,18 +44,25 @@ __all__ = [
     "NOT_GIVEN",
     "AttributeValue",
     "CaptureBudget",
+    "ChatPrompt",
     "Client",
     "LogLevel",
     "LogLevelOption",
     "Mask",
     "MaskContext",
+    "Prompt",
+    "PromptError",
+    "PromptModel",
     "SpanHandle",
     "SpanType",
     "TelemetrySpanProcessor",
+    "TextPrompt",
     "Usage",
     "__version__",
     "flush",
     "get_client",
+    "get_prompt",
+    "get_prompt_async",
     "get_traceparent",
     "init",
     "log",
@@ -54,4 +71,5 @@ __all__ = [
     "shutdown",
     "start_span",
     "update_current_span",
+    "with_prompt",
 ]

{telemetry_dev-0.2.10 → telemetry_dev-0.2.12}/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.10 → telemetry_dev-0.2.12}/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")