@telemetry-dev/sdk 0.1.11 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Pure TypeScript SDK for [telemetry.dev](https://telemetry.dev): add LLM traces, logs, and GenAI
 metrics to any app. Built on OpenTelemetry — spans use the `gen_ai.*` semantic conventions and
-ship as OTLP protobuf to `https://ingest.telemetry.dev`. Works on Node >= 20.19 and edge runtimes
+ship as OTLP protobuf to `https://api.telemetry.dev`. Works on Node >= 20.19 and edge runtimes
 (Vercel Edge, and Cloudflare Workers with Node.js compatibility, which is on by default for
 compatibility dates of 2026-08-04 or later; earlier dates need the `nodejs_compat` flag). ESM-only;
 CJS consumers can `require()` it on Node >= 20.19.
@@ -59,12 +59,16 @@ Without an API key every call is a silent no-op — the SDK never throws into yo
 
 ## Configuration
 
-| Option        | Env var                     | Default                        |
-| ------------- | --------------------------- | ------------------------------ |
-| `apiKey`      | `TELEMETRY_DEV_API_KEY`     | — (absent ⇒ no-op)             |
-| `baseUrl`     | `TELEMETRY_DEV_BASE_URL`    | `https://ingest.telemetry.dev` |
-| `environment` | `TELEMETRY_DEV_ENVIRONMENT` | `production`                   |
-| `serviceName` | `OTEL_SERVICE_NAME`         | `unknown_service`              |
+| Option        | Env var                     | Default                     |
+| ------------- | --------------------------- | --------------------------- |
+| `apiKey`      | `TELEMETRY_DEV_API_KEY`     | — (absent ⇒ no-op)          |
+| `baseUrl`     | `TELEMETRY_DEV_BASE_URL`    | `https://api.telemetry.dev` |
+| `environment` | `TELEMETRY_DEV_ENVIRONMENT` | `production`                |
+| `serviceName` | `OTEL_SERVICE_NAME`         | `unknown_service`           |
+
+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
+`baseUrl` to it.
 
 Other `init()` options: `enabled` (kill switch), `registerGlobal`, `exportMode: "batched" |
 "immediate"`, `captureInput` / `captureOutput`, `mask(value, { key })` redaction hook,
@@ -151,11 +155,13 @@ const pinned = await getPrompt("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. getPrompt 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 reject: 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, getPrompt does not fetch that prompt again before that time
+  (one hour at most). This is the one SDK function that can reject: your app cannot run without
+  its prompt.
 - getPrompt uses the API key and base URL of an enabled `init()`, or `TELEMETRY_DEV_API_KEY` and
   `TELEMETRY_DEV_BASE_URL`, or its own `apiKey`, `baseUrl`, and `fetch` options. It reads the same
-  host that telemetry goes to, `https://ingest.telemetry.dev` by default. The key needs the read
+  host that 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 `propagateAttributes` (or of `sessionMode: "process"`). Without a
@@ -167,12 +173,13 @@ When input capture is on, `td.prompt.variables` holds the JSON of the variables
 `compile()` of that prompt object before `withPrompt` starts, or of the last `compile()` inside
 `fn`, after `mask` and truncation. If tasks that run at the same time share one prompt object, call
 `compile()` in `withPrompt`, or call getPrompt in each task. getPrompt returns a new object from
-the cache. If you do not, a task can record the variables of a different task. Model calls are the
-spans of type `generation` (operations `chat`, `text_completion`, and `generate_content`),
-including the spans of the provider integrations that use this SDK: OpenAI, Anthropic, Amazon
-Bedrock, Google GenAI, and OpenRouter. Spans from the AI SDK and TanStack AI integrations, and from
-other OpenTelemetry tracers, do not get the attributes. Messages from `compile()` that you pass to
-a model call outside `withPrompt` are not recorded.
+the cache. If you do not, a task can record the variables of a different task. Tasks that run at the
+same time inside one `withPrompt` share its variables, so call `withPrompt` in each task that
+compiles its own. Model calls are the spans of type `generation` (operations `chat`,
+`text_completion`, and `generate_content`), including the spans of the provider integrations that
+use this SDK: OpenAI, Anthropic, Amazon Bedrock, Google GenAI, and OpenRouter. Spans from the AI SDK
+and TanStack AI integrations, and from other OpenTelemetry tracers, do not get the attributes.
+Messages from `compile()` that you pass to a model call outside `withPrompt` are not recorded.
 
 ## API
 
@@ -265,7 +272,7 @@ Alternatively `init({ registerGlobal: true })` makes the SDK's provider the app'
 that mode only this SDK's spans are exported by default.
 
 Any vanilla OTel app can also skip the SDK entirely: point a stock OTLP/HTTP protobuf exporter at
-`https://ingest.telemetry.dev/v1/traces` with an `Authorization: Bearer td_live_...` header.
+`https://api.telemetry.dev/v1/traces` with an `Authorization: Bearer td_live_...` header.
 
 ### Native Claude SDK spans
 

package/dist/index.d.mts

@@ -16,7 +16,7 @@ type MaskFn<T = unknown> = (value: T, ctx: {
 interface TelemetryOptions {
   /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the SDK is a no-op. */
   apiKey?: string;
-  /** Base URL for telemetry export and getPrompt. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  /** Base URL for telemetry export and getPrompt. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://api.telemetry.dev`. */
   baseUrl?: string;
   /** Deployment environment label. Falls back to `TELEMETRY_DEV_ENVIRONMENT`, then `production`. */
   environment?: string;
@@ -355,7 +355,7 @@ interface GetPromptOptionsBase {
   cacheTtlSeconds?: number;
   /** API key with the prompts:read scope. Falls back to the initialized client, then `TELEMETRY_DEV_API_KEY`. */
   apiKey?: string;
-  /** Falls back to the initialized client, then `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  /** Falls back to the initialized client, then `TELEMETRY_DEV_BASE_URL`, then `https://api.telemetry.dev`. */
   baseUrl?: string;
   /** Falls back to the initialized client's `fetch`, then `globalThis.fetch`. */
   fetch?: typeof fetch;
@@ -406,7 +406,8 @@ declare function getPrompt(name: string, options?: GetChatPromptOptions): Promis
  * it: the spans get `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 withPrompt starts, or of the last `compile()` inside `fn`, so a compile in
- * another task does not change them once withPrompt runs.
+ * another task does not change them once withPrompt runs. Concurrent tasks in `fn` share the
+ * variables, so call withPrompt in each task that compiles its own.
  */
 declare function withPrompt<T>(prompt: Prompt, fn: () => T): T;
 //#endregion

package/dist/index.mjs

@@ -563,9 +563,13 @@ var PromptError = class extends Error {
 	}
 };
 const FETCH_TIMEOUT_MS = 1e4;
+/** The longest Retry-After that getPrompt honors, so that a bad header cannot stop fetches. */
+const MAX_RETRY_AFTER_MS = 36e5;
 /** How long a failed fetch with no copy answers calls, so that they do not each fetch again. */
 const ERROR_TTL_MS = 1e4;
 const MAX_CACHE_ENTRIES = 1e3;
+/** IMF-fixdate, the HTTP date that servers send: `Sun, 06 Nov 1994 08:49:37 GMT`. */
+const HTTP_DATE = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
 const VARIABLE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
 const MODEL_CALL_OPERATIONS = new Set([
 	"chat",
@@ -575,6 +579,8 @@ const MODEL_CALL_OPERATIONS = new Set([
 const PROMPT_KEY = createContextKey("telemetry.dev prompt");
 const cache = /* @__PURE__ */ new Map();
 const compiledVariables = /* @__PURE__ */ new WeakMap();
+/** The Retry-After of the response that failed with this error, in milliseconds. */
+const retryAfter = /* @__PURE__ */ new WeakMap();
 async function getPrompt(name, options = {}) {
 	const type = options.type ?? "chat";
 	checkOptions(name, options, type);
@@ -635,7 +641,8 @@ async function getPrompt(name, options = {}) {
 * it: the spans get `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 withPrompt starts, or of the last `compile()` inside `fn`, so a compile in
-* another task does not change them once withPrompt runs.
+* another task does not change them once withPrompt runs. Concurrent tasks in `fn` share the
+* variables, so call withPrompt in each task that compiles its own.
 */
 function withPrompt(prompt, fn) {
 	const scope = {
@@ -675,10 +682,13 @@ async function load(key, ttlMs, fetchResponse, onError) {
 	let entry = cache.get(key);
 	if (!entry) {
 		if (cache.size >= MAX_CACHE_ENTRIES) cache.delete(cache.keys().next().value);
-		entry = { checkedAt: 0 };
+		entry = {
+			checkedAt: 0,
+			retryAt: 0
+		};
 		cache.set(key, entry);
 	}
-	const fresh = Date.now() < entry.checkedAt + (entry.response ? ttlMs : Math.min(ttlMs, ERROR_TTL_MS));
+	const fresh = Date.now() < Math.max(entry.checkedAt + (entry.response ? ttlMs : Math.min(ttlMs, ERROR_TTL_MS)), entry.retryAt);
 	if (entry.response) {
 		if (!fresh) entry.pending ??= refresh(entry, fetchResponse, onError);
 		return entry.response;
@@ -689,8 +699,11 @@ async function load(key, ttlMs, fetchResponse, onError) {
 function refresh(entry, fetchResponse, onError) {
 	return fetchResponse().then((response) => {
 		entry.response = response;
+		entry.retryAt = 0;
 		return response;
 	}, (error) => {
+		const delay = error instanceof PromptError ? retryAfter.get(error) : void 0;
+		entry.retryAt = delay === void 0 ? 0 : Date.now() + delay;
 		if (!entry.response) {
 			entry.error = error;
 			throw error;
@@ -715,7 +728,10 @@ async function fetchPrompt(url, headers, fetchImpl) {
 		const body = await res.json().catch(() => void 0);
 		if (!res.ok) {
 			const error = isRecord(body) && isRecord(body.error) ? body.error : {};
-			throw new PromptError(typeof error.code === "string" ? error.code : `http_${res.status}`, typeof error.message === "string" ? error.message : `telemetry.dev returned ${res.status}`, res.status);
+			const failure = new PromptError(typeof error.code === "string" ? error.code : `http_${res.status}`, typeof error.message === "string" ? error.message : `telemetry.dev returned ${res.status}`, res.status);
+			const delay = retryAfterMs(res);
+			if (delay !== void 0) retryAfter.set(failure, delay);
+			throw failure;
 		}
 		const response = parseResponse(body);
 		if (!response) throw new PromptError("invalid_response", "telemetry.dev returned a prompt it cannot read");
@@ -783,6 +799,17 @@ function keyFingerprint(apiKey) {
 	const digest = sha256(new TextEncoder().encode(apiKey)).subarray(0, 16);
 	return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
+/** The Retry-After of a 429 or 503 response, as seconds or an IMF-fixdate HTTP date, capped. */
+function retryAfterMs(res) {
+	if (res.status !== 429 && res.status !== 503) return void 0;
+	const value = res.headers.get("retry-after")?.trim();
+	if (!value) return void 0;
+	let ms;
+	if (/^\d+$/.test(value)) ms = Number(value) * 1e3;
+	else if (HTTP_DATE.test(value)) ms = Date.parse(value) - Date.now();
+	else return void 0;
+	return ms > 0 ? Math.min(ms, MAX_RETRY_AFTER_MS) : void 0;
+}
 function parseResponse(body) {
 	if (!isRecord(body)) return void 0;
 	const { name, type, label, version, rollout } = body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/sdk",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "Pure TypeScript SDK for telemetry.dev: LLM traces, logs, and GenAI metrics on OpenTelemetry, for Node and edge runtimes.",
   "keywords": [
     "genai",
@@ -42,7 +42,7 @@
     "@opentelemetry/sdk-logs": "^0.223.0",
     "@opentelemetry/sdk-metrics": "^2.12.0",
     "@opentelemetry/sdk-trace-base": "^2.12.0",
-    "@telemetry-dev/otel": "^0.1.7"
+    "@telemetry-dev/otel": "^0.2.0"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",

package/src/config.ts

@@ -22,7 +22,7 @@ export type MaskFn<T = unknown> = (value: T, ctx: { key: string }) => T;
 export interface TelemetryOptions {
   /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the SDK is a no-op. */
   apiKey?: string;
-  /** Base URL for telemetry export and getPrompt. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  /** Base URL for telemetry export and getPrompt. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://api.telemetry.dev`. */
   baseUrl?: string;
   /** Deployment environment label. Falls back to `TELEMETRY_DEV_ENVIRONMENT`, then `production`. */
   environment?: string;

package/src/prompts.ts

@@ -118,7 +118,7 @@ interface GetPromptOptionsBase {
   cacheTtlSeconds?: number;
   /** API key with the prompts:read scope. Falls back to the initialized client, then `TELEMETRY_DEV_API_KEY`. */
   apiKey?: string;
-  /** Falls back to the initialized client, then `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  /** Falls back to the initialized client, then `TELEMETRY_DEV_BASE_URL`, then `https://api.telemetry.dev`. */
   baseUrl?: string;
   /** Falls back to the initialized client's `fetch`, then `globalThis.fetch`. */
   fetch?: typeof fetch;
@@ -182,6 +182,8 @@ interface CacheEntry {
   error?: unknown;
   /** When the last fetch ended. */
   checkedAt: number;
+  /** No fetch before this time: the Retry-After of the last 429 or 503 response. */
+  retryAt: number;
   pending?: Promise<PromptResponse>;
 }
 
@@ -192,15 +194,21 @@ interface PromptScope {
 }
 
 const FETCH_TIMEOUT_MS = 10_000;
+/** The longest Retry-After that getPrompt honors, so that a bad header cannot stop fetches. */
+const MAX_RETRY_AFTER_MS = 3_600_000;
 /** How long a failed fetch with no copy answers calls, so that they do not each fetch again. */
 const ERROR_TTL_MS = 10_000;
 const MAX_CACHE_ENTRIES = 1_000;
+/** IMF-fixdate, the HTTP date that servers send: `Sun, 06 Nov 1994 08:49:37 GMT`. */
+const HTTP_DATE = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
 const VARIABLE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
 const MODEL_CALL_OPERATIONS = new Set<unknown>(["chat", "text_completion", "generate_content"]);
 const PROMPT_KEY = createContextKey("telemetry.dev prompt");
 
 const cache = new Map<string, CacheEntry>();
 const compiledVariables = new WeakMap<Prompt, object>();
+/** The Retry-After of the response that failed with this error, in milliseconds. */
+const retryAfter = new WeakMap<PromptError, number>();
 
 /**
  * Fetches a prompt version from telemetry.dev and keeps it. When the copy is older than
@@ -314,7 +322,8 @@ export async function getPrompt(name: string, options: GetPromptOptions = {}): P
  * it: the spans get `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 withPrompt starts, or of the last `compile()` inside `fn`, so a compile in
- * another task does not change them once withPrompt runs.
+ * another task does not change them once withPrompt runs. Concurrent tasks in `fn` share the
+ * variables, so call withPrompt in each task that compiles its own.
  */
 export function withPrompt<T>(prompt: Prompt, fn: () => T): T {
   const scope: PromptScope = { prompt, variables: compiledVariables.get(prompt) };
@@ -397,12 +406,16 @@ async function load(
 
   if (!entry) {
     if (cache.size >= MAX_CACHE_ENTRIES) cache.delete(cache.keys().next().value!);
-    entry = { checkedAt: 0 };
+    entry = { checkedAt: 0, retryAt: 0 };
     cache.set(key, entry);
   }
 
   const fresh =
-    Date.now() < entry.checkedAt + (entry.response ? ttlMs : Math.min(ttlMs, ERROR_TTL_MS));
+    Date.now() <
+    Math.max(
+      entry.checkedAt + (entry.response ? ttlMs : Math.min(ttlMs, ERROR_TTL_MS)),
+      entry.retryAt,
+    );
 
   if (entry.response) {
     if (!fresh) entry.pending ??= refresh(entry, fetchResponse, onError);
@@ -424,10 +437,14 @@ function refresh(
     .then(
       (response) => {
         entry.response = response;
+        entry.retryAt = 0;
 
         return response;
       },
       (error: unknown) => {
+        const delay = error instanceof PromptError ? retryAfter.get(error) : undefined;
+        entry.retryAt = delay === undefined ? 0 : Date.now() + delay;
+
         if (!entry.response) {
           entry.error = error;
           throw error;
@@ -468,11 +485,16 @@ async function fetchPrompt(
     if (!res.ok) {
       const error = isRecord(body) && isRecord(body.error) ? body.error : {};
 
-      throw new PromptError(
+      const failure = new PromptError(
         typeof error.code === "string" ? error.code : `http_${res.status}`,
         typeof error.message === "string" ? error.message : `telemetry.dev returned ${res.status}`,
         res.status,
       );
+
+      const delay = retryAfterMs(res);
+      if (delay !== undefined) retryAfter.set(failure, delay);
+
+      throw failure;
     }
 
     const response = parseResponse(body);
@@ -594,6 +616,23 @@ function keyFingerprint(apiKey: string): string {
   return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 
+/** The Retry-After of a 429 or 503 response, as seconds or an IMF-fixdate HTTP date, capped. */
+function retryAfterMs(res: Response): number | undefined {
+  if (res.status !== 429 && res.status !== 503) return undefined;
+
+  const value = res.headers.get("retry-after")?.trim();
+
+  if (!value) return undefined;
+
+  let ms: number;
+
+  if (/^\d+$/.test(value)) ms = Number(value) * 1000;
+  else if (HTTP_DATE.test(value)) ms = Date.parse(value) - Date.now();
+  else return undefined;
+
+  return ms > 0 ? Math.min(ms, MAX_RETRY_AFTER_MS) : undefined;
+}
+
 function parseResponse(body: unknown): PromptResponse | undefined {
   if (!isRecord(body)) return undefined;
   const { name, type, label, version, rollout } = body;