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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.12
+Version: 0.2.13
 Summary: telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics
 Keywords: telemetry,opentelemetry,llm,genai,tracing,observability
 Author: telemetry.dev
@@ -247,8 +247,10 @@ 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
@@ -264,10 +266,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

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

@@ -222,8 +222,10 @@ 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
@@ -239,10 +241,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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.12"
+version = "0.2.13"
 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.2.13}/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
@@ -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
@@ -347,14 +367,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 +391,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 +442,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 +473,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 +509,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 +552,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 +591,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 +619,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)