@telemetry-dev/sdk 0.1.7 → 0.1.9

package/README.md

@@ -3,8 +3,11 @@
 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
-(Vercel Edge, Cloudflare Workers with `nodejs_compat`). ESM-only; CJS consumers can `require()` it
-on Node >= 20.19.
+(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.
+
+Docs: https://telemetry.dev/docs/sdk/typescript
 
 ```sh
 npm install @telemetry-dev/sdk
@@ -12,10 +15,20 @@ npm install @telemetry-dev/sdk
 
 ## Quickstart
 
+Set `TELEMETRY_DEV_API_KEY` to your project API key. `init()` reads it from the environment.
+
 ```ts
 import { init, observe, startSpan, propagateAttributes, log, flush } from "@telemetry-dev/sdk";
 
-init({ apiKey: "td_live_..." }); // or TELEMETRY_DEV_API_KEY
+init();
+
+// Stand-in for your model client, so the example runs on its own. Replace it with a real call.
+async function callModel(question: string) {
+  return {
+    message: { role: "assistant", content: `You asked: ${question}` },
+    usage: { input: 12, output: 9 },
+  };
+}
 
 const answer = observe(
   async function answer(question: string) {
@@ -25,13 +38,13 @@ const answer = observe(
       provider: "openai",
       input: [{ role: "user", content: question }],
     });
-    const res = await llm.chat(question);
+    const res = await callModel(question);
     generation.end({
-      output: res.message,
+      output: [res.message],
       usage: { inputTokens: res.usage.input, outputTokens: res.usage.output },
     });
     log("generation finished", { attributes: { cached: false } });
-    return res.message;
+    return res.message.content;
   },
   { type: "agent" },
 );
@@ -70,6 +83,12 @@ still record non-content metadata such as response IDs and models, finish reason
 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.
 
+`mask` receives input and output content, system instructions, log messages, log attributes
+other than numbers and booleans, and content that integrations pass to
+`handle.serializeContent`. `ctx.key` names the attribute being written. It does not receive
+span or propagated `metadata`, raw `attributes`, or exception messages and stack traces; redact
+those separately.
+
 Root spans remain independent by default. `init({ sessionMode: "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 context is preserved.
@@ -79,7 +98,7 @@ new ID. It is not persisted across processes.
 `sampler` accepts an OpenTelemetry `Sampler` and overrides `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG`.
 The default is parent-based always-on. Session roots keep the configured root policy.
 Nested spans and explicitly parented spans keep the real parent's policy.
-The SDK installs the [session sampling wrapper](../otel/README.md#correlation-attributes) on its provider. This includes the global provider that Eve uses.
+The SDK installs the [session sampling wrapper](https://github.com/telemetry-dev/telemetry/blob/main/packages/otel/README.md#correlation-attributes) on its provider. This includes the global provider that Eve uses.
 
 ## API
 
@@ -89,6 +108,13 @@ The SDK installs the [session sampling wrapper](../otel/README.md#correlation-at
 - `startSpan(name, options?)` — manual handle; does **not** activate context. `handle.update()`,
   `handle.end()`, `handle.recordOutputChunk(timestampMs?)`, `handle.traceparent`, `handle.span`
   (raw OTel span).
+- `handle.serializeContent(value, key)` — prepare content that an integration writes outside
+  `input` and `output`, such as an error message or a raw attribute, the way `input` and `output`
+  are prepared: the configured `mask` with `key`, JSON stringify (strings pass through), then
+  truncation to `maxAttributeLength`. Returns `undefined` when the mask throws (reported through
+  `onError`) or drops the value, or the value cannot be serialized; write nothing then. It does not
+  check `captureInput` / `captureOutput`. Integrations that support older cores should treat a
+  missing method as a configured mask.
 - `startActiveSpan(name, options?, fn)` — callback-scoped; activates context, auto-ends.
 - `updateActiveSpan(fields)` — update the innermost active span.
 - `propagateAttributes({ userId, sessionId, metadata }, fn)` — stamps `user.id`,
@@ -102,6 +128,8 @@ The SDK installs the [session sampling wrapper](../otel/README.md#correlation-at
   or inject W3C trace context. Baggage is omitted unless `includeBaggage` is true.
 - `captureEnabled("input" | "output")` — report whether the active initialized client permits that
   capture direction. Returns `false` when no client is initialized.
+- `captureMasked()` — report whether the active initialized client has a `mask` configured.
+  Returns `false` when no client is initialized.
 - `boundedCapture(value, options?)` — copy a JSON-compatible value within bounded work and retained
   size. Defaults to 48 KiB, depth 32, and 1,000 traversal items. Returns `{ value, truncated }`;
   `value` can be partial or `undefined` when a limit, cycle, getter, or skip rule prevents capture.
@@ -126,9 +154,9 @@ histogram state and does not retain individual intervals. Pull-based timing incl
 between reads. An explicit timestamp uses the same monotonic millisecond clock for every chunk.
 
 Provider integrations feature-detect stream APIs. With an older core SDK that lacks the stream
-capture policy, streams are still traced with usage, model, finish reason, and timing, but output
-retention assumes the default 65536 limit and treats a mask as configured, so incomplete output is
-withheld. Instrumentation failures are not reported to `onError` with such a core. If only
+capture policy, streams are still traced with usage, model, finish reason, and timing. Output is
+retained within the same fixed bounds as with a current core, but a mask is assumed to be
+configured, so incomplete output is withheld. Instrumentation failures are not reported to `onError` with such a core. If only
 `recordOutputChunk` is unavailable, tracing and reconstruction continue but chunk-interval metrics
 are unavailable. Upgrade the core SDK with provider integrations to enable the full stream
 telemetry.
@@ -163,10 +191,21 @@ 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.
 
+### Native Claude SDK spans
+
+`@anthropic-ai/sdk` 0.134.0 and later emits OpenTelemetry spans natively through the global tracer provider.
+To send these spans to telemetry.dev, refer to [Claude SDK](https://telemetry.dev/docs/integrations/claude-sdk).
+If you use `init({ registerGlobal: true })`, also set `spanFilter: () => true`. The default filter of that mode exports only the spans of this SDK.
+Do not use the native spans and `@telemetry-dev/anthropic` together. If you use the two, each request has two spans.
+
 ## Notes
 
-- AsyncLocalStorage powers context propagation. On runtimes without it (Workers without
-  `nodejs_compat`) automatic nesting is unavailable entirely unless the host app registered its
+- AsyncLocalStorage powers context propagation. On runtimes without it (Cloudflare Workers without
+  Node.js compatibility) automatic nesting is unavailable entirely unless the host app registered its
   own global OTel context manager — pass `parent` explicitly there.
 - `@opentelemetry/api` is a peer dependency (installed automatically by npm/pnpm) so the SDK
   shares the host app's OTel API singleton.
+
+## License
+
+MIT. See [LICENSE](https://github.com/telemetry-dev/telemetry/blob/main/packages/sdk/LICENSE).

package/dist/index.d.mts

@@ -5,7 +5,11 @@ import { BatchOptions, BatchOptions as BatchOptions$1, ExportMode, ExportMode as
 import { PushMetricExporter } from "@opentelemetry/sdk-metrics";
 
 //#region src/config.d.ts
-/** Redaction hook applied to captured content (input/output/log message) before JSON stringification. */
+/**
+ * Redaction hook applied to captured content (input/output, log messages and attributes, and
+ * content passed to `SpanHandle.serializeContent`) before JSON stringification. Not applied to
+ * metadata or raw attributes.
+ */
 type MaskFn<T = unknown> = (value: T, ctx: {
   key: string;
 }) => T;
@@ -154,6 +158,8 @@ interface TelemetryClient {
   shutdown(): Promise<void>;
 }
 declare function captureEnabled(kind: "input" | "output"): boolean;
+/** Whether the active client runs captured values through a mask; false before `init`. */
+declare function captureMasked(): boolean;
 declare function flush(): Promise<void>;
 declare function shutdown(): Promise<void>;
 declare function init(options?: TelemetryOptions, overrides?: ClientOverrides): TelemetryClient;
@@ -209,6 +215,15 @@ interface SpanHandle {
   /** Records an output chunk arrival. Pull-based streams include consumer delay between pulls. */
   recordOutputChunk(timestampMs?: number): void;
   reportError?(cause: unknown): void;
+  /**
+   * Prepares content that the span writes outside `input` and `output` the way those are
+   * prepared: the configured mask with `key` (the attribute the result is written to), JSON
+   * stringify (strings pass through), then truncation to `maxAttributeLength`. Returns undefined
+   * when the mask throws (reported to `onError`) or drops the value, or the value cannot be
+   * serialized. Capture flags are not checked. Absent on cores that predate it; treat a missing
+   * method as masked.
+   */
+  serializeContent?(value: unknown, key: string): string | undefined;
   end(fields?: SpanFields & {
     endTime?: Date | number;
   }): void;
@@ -242,4 +257,4 @@ interface ObserveOptions extends StartSpanOptions {
  */
 declare function observe<TThis, TArgs extends unknown[], TReturn>(fn: (this: TThis, ...args: TArgs) => TReturn, options?: ObserveOptions): (...args: TArgs) => TReturn;
 //#endregion
-export { type AgentFields, type BatchOptions, type BoundedCaptureDetails, type BoundedCaptureOptions, type BoundedCaptureResult, type ClientOverrides, type ExportMode, type GenerationFields, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type PropagatedAttributes, SCOPE_NAME, type SdkLogLevel, type SpanCapturePolicy, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type TokenUsage, type ToolFields, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+export { type AgentFields, type BatchOptions, type BoundedCaptureDetails, type BoundedCaptureOptions, type BoundedCaptureResult, type ClientOverrides, type ExportMode, type GenerationFields, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type PropagatedAttributes, SCOPE_NAME, type SdkLogLevel, type SpanCapturePolicy, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type TokenUsage, type ToolFields, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };

package/dist/index.mjs

@@ -63,6 +63,10 @@ function captureEnabled(kind) {
 	const config = currentClient().core?.config;
 	return kind === "input" ? config?.captureInput ?? false : config?.captureOutput ?? false;
 }
+/** Whether the active client runs captured values through a mask; false before `init`. */
+function captureMasked() {
+	return currentClient().core?.config.mask !== void 0;
+}
 function flush() {
 	return currentClient().flush();
 }
@@ -353,7 +357,7 @@ function prepareCaptureValue(key, value, cfg) {
 	if (cfg.mask) try {
 		masked = cfg.mask(value, { key });
 	} catch (error) {
-		reportError(cfg.onError, error instanceof Error ? error : new Error(String(error)));
+		reportError(cfg.onError, error);
 		return;
 	}
 	const serialized = jsonAttr(masked);
@@ -536,6 +540,7 @@ const NOOP_SPAN_HANDLE = {
 	update: () => NOOP_SPAN_HANDLE,
 	recordOutputChunk: () => {},
 	reportError: () => {},
+	serializeContent: () => void 0,
 	end: () => {}
 };
 //#endregion
@@ -678,6 +683,9 @@ function createSpanHandle(core, name, options = {}) {
 		reportError(cause) {
 			reportError(meta.onError, cause instanceof Error ? cause : new Error(String(cause)));
 		},
+		serializeContent(value, key) {
+			return prepareCaptureValue(key, value, meta.capture);
+		},
 		end(fields) {
 			try {
 				if (fields) applyFields(span, meta, fields);
@@ -805,4 +813,4 @@ function observe(fn, options) {
 	return wrapped;
 }
 //#endregion
-export { SCOPE_NAME, TelemetrySpanProcessor, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+export { SCOPE_NAME, TelemetrySpanProcessor, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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.218.0",
     "@opentelemetry/sdk-metrics": "^2.7.1",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
-    "@telemetry-dev/otel": "^0.1.5"
+    "@telemetry-dev/otel": "^0.1.6"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",

package/src/capture.ts

@@ -271,7 +271,7 @@ export function prepareCaptureValue(
     try {
       masked = cfg.mask(value, { key });
     } catch (error) {
-      reportError(cfg.onError, error instanceof Error ? error : new Error(String(error)));
+      reportError(cfg.onError, error);
 
       return undefined;
     }

package/src/client.ts

@@ -94,6 +94,11 @@ export function captureEnabled(kind: "input" | "output"): boolean {
   return kind === "input" ? (config?.captureInput ?? false) : (config?.captureOutput ?? false);
 }
 
+/** Whether the active client runs captured values through a mask; false before `init`. */
+export function captureMasked(): boolean {
+  return currentClient().core?.config.mask !== undefined;
+}
+
 export function flush(): Promise<void> {
   return currentClient().flush();
 }

package/src/config.ts

@@ -12,7 +12,11 @@ import {
 
 export type { BatchOptions, ExportMode, LogLevel, SdkLogLevel } from "@telemetry-dev/otel";
 
-/** Redaction hook applied to captured content (input/output/log message) before JSON stringification. */
+/**
+ * Redaction hook applied to captured content (input/output, log messages and attributes, and
+ * content passed to `SpanHandle.serializeContent`) before JSON stringification. Not applied to
+ * metadata or raw attributes.
+ */
 export type MaskFn<T = unknown> = (value: T, ctx: { key: string }) => T;
 
 export interface TelemetryOptions {

package/src/index.ts

@@ -9,6 +9,7 @@ export type {
 
 export {
   captureEnabled,
+  captureMasked,
   type ClientOverrides,
   flush,
   init,

package/src/noop.ts

@@ -16,5 +16,6 @@ export const NOOP_SPAN_HANDLE: SpanHandle = {
   update: () => NOOP_SPAN_HANDLE,
   recordOutputChunk: () => {},
   reportError: () => {},
+  serializeContent: () => undefined,
   end: () => {},
 };

package/src/span.ts

@@ -38,6 +38,7 @@ import {
   type SpanFields,
   type SpanType,
 } from "./attrs.ts";
+import { prepareCaptureValue } from "./capture.ts";
 import { type ClientCore, currentClient } from "./client.ts";
 import { NOOP_SPAN_HANDLE } from "./noop.ts";
 
@@ -80,6 +81,15 @@ export interface SpanHandle {
   /** Records an output chunk arrival. Pull-based streams include consumer delay between pulls. */
   recordOutputChunk(timestampMs?: number): void;
   reportError?(cause: unknown): void;
+  /**
+   * Prepares content that the span writes outside `input` and `output` the way those are
+   * prepared: the configured mask with `key` (the attribute the result is written to), JSON
+   * stringify (strings pass through), then truncation to `maxAttributeLength`. Returns undefined
+   * when the mask throws (reported to `onError`) or drops the value, or the value cannot be
+   * serialized. Capture flags are not checked. Absent on cores that predate it; treat a missing
+   * method as masked.
+   */
+  serializeContent?(value: unknown, key: string): string | undefined;
   end(fields?: SpanFields & { endTime?: Date | number }): void;
 }
 
@@ -303,6 +313,9 @@ export function createSpanHandle(
     reportError(cause) {
       reportError(meta.onError, cause instanceof Error ? cause : new Error(String(cause)));
     },
+    serializeContent(value, key) {
+      return prepareCaptureValue(key, value, meta.capture);
+    },
     end(fields) {
       try {
         if (fields) applyFields(span, meta, fields);