@telemetry-dev/sdk 0.1.8 → 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`,
@@ -165,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;
@@ -211,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;

package/dist/index.mjs

@@ -357,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);
@@ -540,6 +540,7 @@ const NOOP_SPAN_HANDLE = {
 	update: () => NOOP_SPAN_HANDLE,
 	recordOutputChunk: () => {},
 	reportError: () => {},
+	serializeContent: () => void 0,
 	end: () => {}
 };
 //#endregion
@@ -682,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/sdk",
-  "version": "0.1.8",
+  "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/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/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);