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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.13
+Version: 0.3.1
 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
@@ -253,7 +257,7 @@ pinned = telemetry_dev.get_prompt("support/reply", version=13)
   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
@@ -272,8 +276,9 @@ ran in it, or before it started in the code that started it; with none, it recor
 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.
+other OpenTelemetry tracers do not get the attributes. A model call outside `with_prompt` does not
+get the attributes, even when it sends messages from `compile()`; with input capture on, the call
+still records those messages as its input.
 
 ## Auto-metrics
 
@@ -331,7 +336,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. |
@@ -399,7 +404,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()
@@ -407,7 +412,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.13 → telemetry_dev-0.3.1}/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
@@ -228,7 +232,7 @@ pinned = telemetry_dev.get_prompt("support/reply", version=13)
   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
@@ -247,8 +251,9 @@ ran in it, or before it started in the code that started it; with none, it recor
 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.
+other OpenTelemetry tracers do not get the attributes. A model call outside `with_prompt` does not
+get the attributes, even when it sends messages from `compile()`; with input capture on, the call
+still records those messages as its input.
 
 ## Auto-metrics
 
@@ -306,7 +311,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. |
@@ -374,7 +379,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()
@@ -382,7 +387,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.13 → telemetry_dev-0.3.1}/pyproject.toml

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

{telemetry_dev-0.2.13 → telemetry_dev-0.3.1}/pyproject.toml.orig

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

{telemetry_dev-0.2.13 → telemetry_dev-0.3.1}/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.13 → telemetry_dev-0.3.1}/src/telemetry_dev/_prompts.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import copy
 import hashlib
 import json
 import random
 import re
+import socket
 import threading
 import urllib.error
 import urllib.parse
@@ -26,7 +28,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,
@@ -274,7 +276,8 @@ def prompt_attributes(
     client: Client, context: Context | None, operation: object, capture_input: bool
 ) -> dict[str, AttributeValue]:
     """The td.prompt.* attributes for a span with this operation that starts in ``context``."""
-    if operation not in _MODEL_CALL_OPERATIONS:
+    # An attribute can be a list, which a frozenset cannot hold.
+    if not isinstance(operation, str) or operation not in _MODEL_CALL_OPERATIONS:
         return {}
     scope = otel_context.get_value(_PROMPT_KEY, context) or otel_context.get_value(_PROMPT_KEY)
     if not isinstance(scope, _PromptScope):
@@ -333,7 +336,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,
         )
@@ -461,10 +470,9 @@ def _load(
     on_error: Callable[[BaseException], None] | None,
 ) -> dict[str, Any]:
     """Return the kept copy of a prompt, and fetch a new copy in a background thread when it is
-    older than the TTL. Only a call with no copy waits for a fetch, until the fetch's deadline: the
-    timeout of urllib applies to each socket operation, not to the whole fetch. A failed fetch with
-    no copy fails the calls of the next ``_ERROR_TTL_S`` (or the TTL, if it is shorter) without a
-    fetch."""
+    older than the TTL. Only a call with no copy waits for a fetch, until the fetch's deadline. A
+    failed fetch with no copy fails the calls of the next ``_ERROR_TTL_S`` (or the TTL, if it is
+    shorter) without a fetch."""
     with _cache_lock:
         entry = _cache.get(key)
         if entry is None:
@@ -483,7 +491,7 @@ def _load(
             return entry.response
         pending, deadline = entry.pending, entry.deadline
     if pending is not None and not pending.wait(deadline - monotonic()):
-        raise PromptError("timeout", f"Fetching the prompt took more than {_FETCH_TIMEOUT_S:g} s")
+        raise _timeout()
     with _cache_lock:
         response, error = entry.response, entry.error
     if response is not None:
@@ -542,31 +550,141 @@ class _NoRedirect(urllib.request.HTTPRedirectHandler):
         return None
 
 
-_opener = urllib.request.build_opener(_NoRedirect)
+class _Deadline:
+    """Ends one prompt fetch after ``_FETCH_TIMEOUT_S``. The timeout of urllib applies to each
+    socket operation, so a server that sends a byte now and then could keep a fetch reading forever,
+    and each address of a host gets the full timeout to connect. A connection attempt gets only the
+    time that is left, and at the deadline this shuts the connection down, which ends a blocked
+    read. It cannot stop an address lookup; the system resolver bounds that."""
+
+    def __init__(self) -> None:
+        self.expired = False
+        self._end = monotonic() + _FETCH_TIMEOUT_S
+        self._lock = threading.Lock()
+        self._sockets: list[socket.socket] = []
+        self._timer = threading.Timer(_FETCH_TIMEOUT_S, self._expire)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def connect(
+        self,
+        address: tuple[str, int],
+        timeout: float | None,
+        source_address: tuple[str, int] | None = None,
+    ) -> socket.socket:
+        """``socket.create_connection``, with each attempt bounded by the deadline."""
+        host, port = address
+        error: OSError = OSError(f"no address for {host}")
+        for family, kind, proto, _, target in socket.getaddrinfo(host, port, 0, socket.SOCK_STREAM):
+            left = self._end - monotonic()
+            if left <= 0:
+                break
+            sock = socket.socket(family, kind, proto)
+            try:
+                sock.settimeout(left if timeout is None else min(left, timeout))
+                if source_address is not None:
+                    sock.bind(source_address)
+                sock.connect(target)
+                sock.settimeout(timeout)
+            except OSError as exc:
+                sock.close()
+                error = exc
+                continue
+            with self._lock:
+                if not self.expired:
+                    try:
+                        # A TLS wrap takes the file descriptor of sock, so keep a copy to shut down.
+                        self._sockets.append(sock.dup())
+                    except OSError:
+                        sock.close()
+                        raise
+                    return sock
+            sock.close()
+            break
+        if self.expired or self._end <= monotonic():
+            raise TimeoutError("the prompt fetch passed its deadline")
+        raise error
+
+    def _expire(self) -> None:
+        with self._lock:
+            self.expired = True
+            for sock in self._sockets:
+                with contextlib.suppress(OSError):
+                    sock.shutdown(socket.SHUT_RDWR)
+
+    def close(self) -> None:
+        self._timer.cancel()
+        with self._lock:
+            for sock in self._sockets:
+                sock.close()
+            self._sockets.clear()
+
+
+class _Request(urllib.request.Request):
+    def __init__(self, url: str, headers: dict[str, str], deadline: _Deadline) -> None:
+        super().__init__(url, headers=headers, method="GET")
+        self.deadline = deadline
+
+
+def _on_deadline(http_class: Any, request: urllib.request.Request) -> Any:
+    """``http_class``, with the sockets of a ``_Request`` under its deadline."""
+
+    def connection(host: str, **kwargs: Any) -> Any:
+        conn = http_class(host, **kwargs)
+        if isinstance(request, _Request):
+            conn._create_connection = request.deadline.connect
+        return conn
+
+    return connection
+
+
+class _HTTPHandler(urllib.request.HTTPHandler):
+    def do_open(self, http_class: Any, req: urllib.request.Request, **http_conn_args: Any) -> Any:
+        return super().do_open(_on_deadline(http_class, req), req, **http_conn_args)
+
+
+class _HTTPSHandler(urllib.request.HTTPSHandler):
+    def do_open(self, http_class: Any, req: urllib.request.Request, **http_conn_args: Any) -> Any:
+        return super().do_open(_on_deadline(http_class, req), req, **http_conn_args)
+
+
+_opener = urllib.request.build_opener(_NoRedirect, _HTTPHandler, _HTTPSHandler)
 
 
 def _fetch(url: str, headers: dict[str, str]) -> dict[str, Any]:
-    request = urllib.request.Request(url, headers=headers, method="GET")
+    deadline = _Deadline()
+    retry_after: str | None = None
     try:
-        with _opener.open(request, timeout=_FETCH_TIMEOUT_S) as response:
-            body: bytes = response.read()
-    except urllib.error.HTTPError as exc:
-        with exc:
-            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"
-        ) from exc
-    except (urllib.error.URLError, OSError) as exc:
-        if isinstance(getattr(exc, "reason", None), TimeoutError):
-            raise PromptError(
-                "timeout", f"Fetching the prompt took more than {_FETCH_TIMEOUT_S:g} s"
-            ) from exc
-        raise PromptError("network_error", "Could not reach telemetry.dev") from exc
+        try:
+            with _opener.open(
+                _Request(url, headers, deadline), timeout=_FETCH_TIMEOUT_S
+            ) as response:
+                status: int = response.status
+                body: bytes = response.read()
+        except urllib.error.HTTPError as exc:
+            with exc:
+                status, body = exc.code, exc.read()
+                retry_after = exc.headers.get("Retry-After")
+    except Exception as exc:
+        if (
+            deadline.expired
+            or isinstance(exc, TimeoutError)
+            or isinstance(getattr(exc, "reason", None), TimeoutError)
+        ):
+            raise _timeout() from exc
+        if isinstance(exc, (urllib.error.URLError, OSError)):
+            raise PromptError("network_error", "Could not reach telemetry.dev") from exc
+        raise
+    finally:
+        deadline.close()
+    # A read that the deadline cut short can end without an error, with part of the body.
+    if deadline.expired:
+        raise _timeout()
+    if not 200 <= status < 300:
+        error = _api_error(status, body)
+        if status in (429, 503):
+            error._retry_after = _retry_after(retry_after)  # pyright: ignore[reportPrivateUsage]
+        raise error
     try:
         parsed = _parse_response(json.loads(body))
     except ValueError:
@@ -576,6 +694,10 @@ def _fetch(url: str, headers: dict[str, str]) -> dict[str, Any]:
     return parsed
 
 
+def _timeout() -> PromptError:
+    return PromptError("timeout", f"Fetching the prompt took more than {_FETCH_TIMEOUT_S:g} s")
+
+
 def _api_error(status: int, body: bytes) -> PromptError:
     try:
         error = json.loads(body).get("error")