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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.12
+Version: 0.3.0
 Summary: telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics
 Keywords: telemetry,opentelemetry,llm,genai,tracing,observability
 Author: telemetry.dev
@@ -81,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` | Base URL for telemetry export and `get_prompt` (trailing slashes stripped). |
+| `TELEMETRY_DEV_BASE_URL` | `https://api.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. |
@@ -89,6 +89,10 @@ routed to the `on_error` hook / `telemetry_dev` logger — never raised into you
 
 Explicit `init()` arguments take precedence over environment variables.
 
+Earlier versions sent data to `https://ingest.telemetry.dev` by default. That hostname reaches the
+same service and stays supported: if a firewall allows only it, set `TELEMETRY_DEV_BASE_URL` or
+`base_url` to it.
+
 Root spans remain independent by default. `telemetry_dev.init(session_mode="process")` groups
 otherwise uncorrelated spans and logs using a fresh opaque UUID for each enabled SDK
 initialization. Explicit and propagated session IDs take precedence, and valid parent trace
@@ -247,11 +251,13 @@ pinned = telemetry_dev.get_prompt("support/reply", version=13)
   `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.
+  seconds (or the TTL, if it is shorter) get the same result without a fetch. After a 429 or 503
+  response with a `Retry-After` header, `get_prompt` does not fetch that prompt again before that
+  time (one hour at most). 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
+  telemetry goes to, `https://api.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
@@ -264,10 +270,13 @@ When input capture is on, `td.prompt.variables` holds the JSON of the variables
 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
+of a different thread. Inside one `with_prompt`, an asyncio task records the last `compile()` that
+ran in it, or before it started in the code that started it; with none, it records the last
+`compile()` in the block. A `compile()` in a worker thread, as with `asyncio.to_thread`, counts only
+for code that has not compiled in its own task. 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
@@ -326,7 +335,7 @@ from telemetry_dev import TelemetrySpanProcessor
 | Option | Default | Purpose |
 | --- | --- | --- |
 | `api_key` | `TELEMETRY_DEV_API_KEY` | Ingest key. Absent with no `span_exporter` = inert no-op. |
-| `base_url` | `TELEMETRY_DEV_BASE_URL` or `https://ingest.telemetry.dev` | Ingest base URL; trailing slashes are stripped. |
+| `base_url` | `TELEMETRY_DEV_BASE_URL` or `https://api.telemetry.dev` | Base URL; trailing slashes are stripped. |
 | `export_mode` | `"batched"` | `"batched"` or `"immediate"` span export. |
 | `max_export_batch_size` | `64` | BatchSpanProcessor export batch size. |
 | `schedule_delay_millis` | `1000` | BatchSpanProcessor schedule delay. |
@@ -394,7 +403,7 @@ from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
 exporter = OTLPSpanExporter(
-    endpoint="https://ingest.telemetry.dev/v1/traces",
+    endpoint="https://api.telemetry.dev/v1/traces",
     headers={"Authorization": f"Bearer {os.environ['TELEMETRY_DEV_API_KEY']}"},
 )
 provider = TracerProvider()
@@ -402,7 +411,7 @@ 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).
+The Claude API can also send server-side spans to telemetry.dev through a Console destination. Set the endpoint to `https://api.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.
 

{telemetry_dev-0.2.12 → telemetry_dev-0.3.0}/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` | Base URL for telemetry export and `get_prompt` (trailing slashes stripped). |
+| `TELEMETRY_DEV_BASE_URL` | `https://api.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. |
@@ -64,6 +64,10 @@ routed to the `on_error` hook / `telemetry_dev` logger — never raised into you
 
 Explicit `init()` arguments take precedence over environment variables.
 
+Earlier versions sent data to `https://ingest.telemetry.dev` by default. That hostname reaches the
+same service and stays supported: if a firewall allows only it, set `TELEMETRY_DEV_BASE_URL` or
+`base_url` to it.
+
 Root spans remain independent by default. `telemetry_dev.init(session_mode="process")` groups
 otherwise uncorrelated spans and logs using a fresh opaque UUID for each enabled SDK
 initialization. Explicit and propagated session IDs take precedence, and valid parent trace
@@ -222,11 +226,13 @@ pinned = telemetry_dev.get_prompt("support/reply", version=13)
   `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.
+  seconds (or the TTL, if it is shorter) get the same result without a fetch. After a 429 or 503
+  response with a `Retry-After` header, `get_prompt` does not fetch that prompt again before that
+  time (one hour at most). 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
+  telemetry goes to, `https://api.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
@@ -239,10 +245,13 @@ When input capture is on, `td.prompt.variables` holds the JSON of the variables
 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
+of a different thread. Inside one `with_prompt`, an asyncio task records the last `compile()` that
+ran in it, or before it started in the code that started it; with none, it records the last
+`compile()` in the block. A `compile()` in a worker thread, as with `asyncio.to_thread`, counts only
+for code that has not compiled in its own task. 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
@@ -301,7 +310,7 @@ from telemetry_dev import TelemetrySpanProcessor
 | Option | Default | Purpose |
 | --- | --- | --- |
 | `api_key` | `TELEMETRY_DEV_API_KEY` | Ingest key. Absent with no `span_exporter` = inert no-op. |
-| `base_url` | `TELEMETRY_DEV_BASE_URL` or `https://ingest.telemetry.dev` | Ingest base URL; trailing slashes are stripped. |
+| `base_url` | `TELEMETRY_DEV_BASE_URL` or `https://api.telemetry.dev` | Base URL; trailing slashes are stripped. |
 | `export_mode` | `"batched"` | `"batched"` or `"immediate"` span export. |
 | `max_export_batch_size` | `64` | BatchSpanProcessor export batch size. |
 | `schedule_delay_millis` | `1000` | BatchSpanProcessor schedule delay. |
@@ -369,7 +378,7 @@ from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
 exporter = OTLPSpanExporter(
-    endpoint="https://ingest.telemetry.dev/v1/traces",
+    endpoint="https://api.telemetry.dev/v1/traces",
     headers={"Authorization": f"Bearer {os.environ['TELEMETRY_DEV_API_KEY']}"},
 )
 provider = TracerProvider()
@@ -377,7 +386,7 @@ 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).
+The Claude API can also send server-side spans to telemetry.dev through a Console destination. Set the endpoint to `https://api.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.
 

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

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

{telemetry_dev-0.2.12 → telemetry_dev-0.3.0}/pyproject.toml.orig

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

{telemetry_dev-0.2.12 → telemetry_dev-0.3.0}/src/telemetry_dev/_config.py

@@ -8,7 +8,7 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Literal
 
-DEFAULT_BASE_URL = "https://ingest.telemetry.dev"
+DEFAULT_BASE_URL = "https://api.telemetry.dev"
 
 
 def _resolve_version() -> str:

{telemetry_dev-0.2.12 → telemetry_dev-0.3.0}/src/telemetry_dev/_prompts.py

@@ -13,8 +13,11 @@ import urllib.request
 from collections import OrderedDict
 from collections.abc import Callable, Generator, Mapping
 from contextlib import contextmanager
+from contextvars import ContextVar
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from email.message import Message
+from email.utils import parsedate_to_datetime
 from time import monotonic
 from typing import IO, Any, Literal, TypeAlias, TypedDict, cast, overload
 from weakref import WeakKeyDictionary
@@ -23,7 +26,7 @@ from opentelemetry import context as otel_context
 from opentelemetry.context import Context
 
 from ._client import Client, get_client
-from ._config import report_error, resolve_config
+from ._config import SDK_VERSION, report_error, resolve_config
 from ._context import propagated_attributes
 from ._semconv import (
     ATTR_PROMPT_LABEL,
@@ -37,7 +40,11 @@ from ._serialize import AttributeValue, json_dumps
 _FETCH_TIMEOUT_S = 10.0
 # How long a failed fetch with no copy answers calls, so that they do not each fetch again.
 _ERROR_TTL_S = 10.0
+# The longest Retry-After that get_prompt honors, so that a bad header cannot stop fetches.
+_MAX_RETRY_AFTER_S = 3600.0
 _MAX_CACHE_ENTRIES = 1000
+# IMF-fixdate, the HTTP date that servers send: Sun, 06 Nov 1994 08:49:37 GMT.
+_HTTP_DATE = re.compile(r"[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT", re.ASCII)
 _VARIABLE = re.compile(r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}")
 _MODEL_CALL_OPERATIONS = frozenset({"chat", "text_completion", "generate_content"})
 _PROMPT_KEY = otel_context.create_key("telemetry_dev.prompt")
@@ -61,6 +68,8 @@ class PromptError(Exception):
         self.code = code
         self.message = message
         self.status = status
+        # The Retry-After of a 429 or 503 response, in seconds.
+        self._retry_after: float | None = None
 
 
 @dataclass(frozen=True, eq=False)
@@ -243,12 +252,21 @@ def with_prompt(prompt: Prompt) -> Generator[None]:
     ``td.prompt.name``, ``td.prompt.version``, ``td.prompt.label``, and, when input capture is on,
     ``td.prompt.variables``. The variables are those of the last ``compile()`` of this prompt
     object before the context starts, or of the last ``compile()`` inside it, so a compile in
-    another thread or task does not change them once the context runs."""
+    another thread or task does not change them once the context runs. When concurrent tasks in
+    the context each compile, a span records the last compile of its own task; a compile in a
+    worker thread (``asyncio.to_thread``) counts only for a task that has not compiled."""
     scope = _PromptScope(prompt, _compiled_variables.get(prompt))
     token = otel_context.attach(otel_context.set_value(_PROMPT_KEY, scope))
+    task_token = _task_variables.set(_task_variables.get())
     try:
         yield
     finally:
+        try:
+            _task_variables.reset(task_token)
+        except ValueError:
+            # The block ended in another Context, as a generator closed elsewhere does. Keep
+            # going like otel_context.detach does, so that the detach below still runs.
+            pass
         otel_context.detach(token)
 
 
@@ -267,8 +285,10 @@ def prompt_attributes(
         attrs[ATTR_PROMPT_VERSION] = prompt.version
     if prompt.label is not None:
         attrs[ATTR_PROMPT_LABEL] = prompt.label
-    if scope.variables is not None and capture_input:
-        serialized = client.serialize(scope.variables, ATTR_PROMPT_VARIABLES)
+    task = _task_variables.get()
+    variables = task[1] if task is not None and task[0] is scope else scope.variables
+    if variables is not None and capture_input:
+        serialized = client.serialize(variables, ATTR_PROMPT_VARIABLES)
         if serialized is not None:
             attrs[ATTR_PROMPT_VARIABLES] = serialized
     return attrs
@@ -313,7 +333,13 @@ def _get_prompt(
             cache_ttl_seconds,
             lambda: _fetch(
                 f"{url}/v1/prompts?{urllib.parse.urlencode(query)}",
-                {"Authorization": f"Bearer {key}", "X-Telemetry-Dev-SDK": "telemetry-dev"},
+                {
+                    "Authorization": f"Bearer {key}",
+                    "X-Telemetry-Dev-SDK": "telemetry-dev",
+                    # urllib's default User-Agent, Python-urllib/3.x, is refused by bot filters
+                    # such as Cloudflare's Browser Integrity Check.
+                    "User-Agent": f"telemetry-dev-python/{SDK_VERSION}",
+                },
             ),
             on_error,
         )
@@ -347,14 +373,22 @@ _compiled_variables: WeakKeyDictionary[ChatPrompt | TextPrompt, dict[str, Any]]
 )
 
 
-@dataclass
+@dataclass(eq=False)
 class _PromptScope:
-    """The prompt of a ``with_prompt`` context and the variables that its spans record."""
+    """The prompt of a ``with_prompt`` context and the variables of the last ``compile()`` in it.
+    Concurrent tasks in the context share the scope; see ``_task_variables``."""
 
     prompt: Prompt
     variables: dict[str, Any] | None
 
 
+# The variables of the last compile() of a scope in the current task. A new asyncio task or a
+# copied context gets a copy, so its compile does not change the value of other tasks.
+_task_variables: ContextVar[tuple[_PromptScope, dict[str, Any]] | None] = ContextVar(
+    "telemetry_dev_prompt_variables", default=None
+)
+
+
 def _record(
     prompt: Prompt, variables: Mapping[str, Any] | None, kwargs: Mapping[str, Any]
 ) -> dict[str, Any]:
@@ -363,6 +397,7 @@ def _record(
     scope = otel_context.get_value(_PROMPT_KEY)
     if isinstance(scope, _PromptScope) and scope.prompt is prompt:
         scope.variables = values
+        _task_variables.set((scope, values))
     return values
 
 
@@ -413,6 +448,8 @@ class _Entry:
     error: Exception | None = None
     # When the last fetch ended.
     checked_at: float = 0.0
+    # No fetch before this time: the Retry-After of the last 429 or 503 response.
+    retry_at: float = 0.0
     # Set when the running fetch ends.
     pending: threading.Event | None = None
     # When calls stop waiting for the running fetch.
@@ -442,7 +479,7 @@ def _load(
             entry = _cache[key] = _Entry()
         now = monotonic()
         ttl = ttl_seconds if entry.response is not None else min(ttl_seconds, _ERROR_TTL_S)
-        if now >= entry.checked_at + ttl and entry.pending is None:
+        if now >= max(entry.checked_at + ttl, entry.retry_at) and entry.pending is None:
             entry.pending = threading.Event()
             entry.deadline = now + _FETCH_TIMEOUT_S
             threading.Thread(
@@ -478,6 +515,12 @@ def _refresh(
         error = exc
     with _cache_lock:
         stale = entry.response
+        delay = (
+            error._retry_after  # pyright: ignore[reportPrivateUsage]
+            if isinstance(error, PromptError)
+            else None
+        )
+        entry.retry_at = 0.0 if delay is None else monotonic() + delay
         if response is not None:
             entry.response = response
         elif stale is None:
@@ -515,7 +558,11 @@ def _fetch(url: str, headers: dict[str, str]) -> dict[str, Any]:
             body: bytes = response.read()
     except urllib.error.HTTPError as exc:
         with exc:
-            raise _api_error(exc.code, exc.read()) from None
+            error = _api_error(exc.code, exc.read())
+            if exc.code in (429, 503):
+                retry_after = _retry_after(exc.headers.get("Retry-After"))
+                error._retry_after = retry_after  # pyright: ignore[reportPrivateUsage]
+            raise error from None
     except TimeoutError as exc:
         raise PromptError(
             "timeout", f"Fetching the prompt took more than {_FETCH_TIMEOUT_S:g} s"
@@ -550,6 +597,25 @@ def _api_error(status: int, body: bytes) -> PromptError:
     )
 
 
+def _retry_after(value: str | None) -> float | None:
+    """Seconds to wait from a Retry-After header of seconds or an IMF-fixdate HTTP date
+    (``Sun, 06 Nov 1994 08:49:37 GMT``), capped."""
+    value = (value or "").strip()
+    if not value:
+        return None
+    if value.isascii() and value.isdigit():
+        seconds = float(value)
+    elif _HTTP_DATE.fullmatch(value):
+        try:
+            date = parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+        seconds = (date - datetime.now(timezone.utc)).total_seconds()
+    else:
+        return None
+    return min(seconds, _MAX_RETRY_AFTER_S) if seconds > 0 else None
+
+
 def _parse_response(data: object) -> dict[str, Any] | None:
     if not isinstance(data, dict):
         return None
@@ -559,6 +625,7 @@ def _parse_response(data: object) -> dict[str, Any] | None:
     if (
         not isinstance(body.get("name"), str)
         or prompt_type not in ("chat", "text")
+        or "label" not in body
         or not (label is None or isinstance(label, str))
         or not _is_version(body.get("version"))
         or not _valid_content(body, prompt_type)