@telemetry-dev/sdk 0.1.8 → 0.1.10

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" },
 );
@@ -65,10 +78,27 @@ other string attribute is cut at the cap without a marker, except that a cap of
 `exportTimeoutMillis` 30000), `spanFilter`, `resourceAttributes`, `logLevel` (SDK diagnostics,
 default `"warn"`), `fetch`, `waitUntil`, `onError`.
 
+Core SDK error recording keeps failure status, error type, and an exception event. It includes
+`exception.message` and `exception.stacktrace` only when both effective `captureInput` and
+`captureOutput` are true, including per-span overrides: exceptions can echo either inputs or
+outputs. The policy is per span: when an error propagates to an enclosing span whose capture is on,
+that span records its message and stack. Included fields pass through `mask` with their exception
+attribute keys, then serialization and truncation. A throwing mask drops the affected field and reports a generic error to `onError`
+and SDK diagnostics without the hook's original message or cause. The original application error
+is rethrown unchanged. These controls do not scrub error type names, metadata, identifiers, resource
+attributes, or events written directly through raw OpenTelemetry APIs.
+
 `captureInput: false` and `captureOutput: false` omit captured content. Provider integrations may
 still record non-content metadata such as response IDs and models, finish reasons, usage, timing,
-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.
+and error types. 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;
+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`, including captured exception messages and stack traces. `ctx.key` names
+the attribute being written. It does not receive span or propagated `metadata` or raw `attributes`;
+redact those separately. Log masking is independent of span capture flags.
 
 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.
@@ -79,7 +109,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 +119,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 +202,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`), including exception messages/stacks, before
+ * JSON stringification. Not applied to metadata or raw attributes.
+ */
 type MaskFn<T = unknown> = (value: T, ctx: {
   key: string;
 }) => T;
@@ -28,9 +32,9 @@ interface TelemetryOptions {
   exportMode?: ExportMode$1;
   /** OTel sampling policy. Defaults to OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG. */
   sampler?: Sampler;
-  /** Capture span inputs (args, prompts) by default. Default true. */
+  /** Capture span inputs (args, prompts). False also omits exception messages/stacks. Default true. */
   captureInput?: boolean;
-  /** Capture span outputs (results, completions) by default. Default true. */
+  /** Capture span outputs (results, completions). False also omits exception messages/stacks. Default true. */
   captureOutput?: boolean;
   /** Redaction hook run on captured content before stringify/truncate. */
   mask?: MaskFn;
@@ -53,7 +57,7 @@ interface TelemetryOptions {
   fetch?: typeof fetch;
   /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `flush()` does not await exports. */
   waitUntil?: (p: Promise<unknown>) => void;
-  /** Receives errors raised while emitting telemetry; repeated instrumentation failures from one stream may be coalesced into one report. The SDK never throws into user code. */
+  /** Receives errors raised while emitting telemetry; repeated instrumentation failures from one stream may be coalesced into one report. A series of failed exports is reported once, and the next failure after an export reaches the ingest is reported again. The SDK never throws into user code. */
   onError?: (cause: Error) => void;
   /** Header value for a custom telemetry.dev integration. */
   sdkName?: string;
@@ -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

@@ -3,7 +3,7 @@ import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator, p
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchLogRecordProcessor, LoggerProvider, SimpleLogRecordProcessor } from "@opentelemetry/sdk-logs";
 import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
-import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, DURATION_BUCKETS, OUTPUT_CHUNK_HISTOGRAM, PROPAGATED_KEY, SCOPE_NAME, SCOPE_NAME as SCOPE_NAME$1, SCOPE_VERSION, StampingSpanProcessor, TelemetrySpanProcessor, activeContext, activeContext as activeContext$1, als, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, sessionIdOf, sessionRootTracerProvider, sessionSampler, setLogLevel, withContext, withContext as withContext$1, withSessionParent } from "@telemetry-dev/otel";
+import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, DURATION_BUCKETS, OUTPUT_CHUNK_HISTOGRAM, PROPAGATED_KEY, SCOPE_NAME, SCOPE_NAME as SCOPE_NAME$1, SCOPE_VERSION, StampingSpanProcessor, TelemetrySpanProcessor, activeContext, activeContext as activeContext$1, als, createExportFailures, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, sessionIdOf, sessionRootTracerProvider, sessionSampler, setLogLevel, withContext, withContext as withContext$1, withSessionParent } from "@telemetry-dev/otel";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 //#region src/config.ts
 const DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536;
@@ -102,9 +102,11 @@ function initInner(options, overrides) {
 		"deployment.environment.name": config.environment,
 		...config.resourceAttributes
 	});
+	const failures = createExportFailures(config.onError);
 	const transport = {
 		fetchImpl: config.fetchImpl,
-		onError: config.onError
+		onError: config.onError,
+		failures
 	};
 	const headers = config.apiKey ? otlpHeaders(config.apiKey, config.sdkName) : void 0;
 	const spanExporter = overrides?.spanExporter ?? createTraceExporter({
@@ -154,7 +156,7 @@ function initInner(options, overrides) {
 	const ensureLogger = () => {
 		if (!logExporter) return void 0;
 		if (!logs) {
-			const logProcessor = config.exportMode === "immediate" ? new SimpleLogRecordProcessor(logExporter) : new BatchLogRecordProcessor(logExporter);
+			const logProcessor = config.exportMode === "immediate" ? new SimpleLogRecordProcessor({ exporter: logExporter }) : new BatchLogRecordProcessor({ exporter: logExporter });
 			const loggerProvider = new LoggerProvider({
 				resource,
 				logRecordLimits: { attributeValueLengthLimit: backstopLength },
@@ -173,7 +175,7 @@ function initInner(options, overrides) {
 		const parts = [provider[op]()];
 		if (logs) parts.push(logs[op]());
 		if (metrics) parts.push(metrics[op]());
-		return Promise.all(parts).then(() => void 0).catch((error) => reportError(config.onError, error));
+		return Promise.all(parts).then(() => void 0).catch((error) => failures.report(error));
 	};
 	const handoff = (p) => {
 		if (config.waitUntil) {
@@ -356,8 +358,8 @@ function prepareCaptureValue(key, value, cfg) {
 	let masked = value;
 	if (cfg.mask) try {
 		masked = cfg.mask(value, { key });
-	} catch (error) {
-		reportError(cfg.onError, error instanceof Error ? error : new Error(String(error)));
+	} catch {
+		reportError(cfg.onError, /* @__PURE__ */ new Error("mask hook raised; content dropped"));
 		return;
 	}
 	const serialized = jsonAttr(masked);
@@ -540,6 +542,7 @@ const NOOP_SPAN_HANDLE = {
 	update: () => NOOP_SPAN_HANDLE,
 	recordOutputChunk: () => {},
 	reportError: () => {},
+	serializeContent: () => void 0,
 	end: () => {}
 };
 //#endregion
@@ -576,16 +579,16 @@ function resolveParent(parent) {
 	if (isContext(ref)) return withAmbientPropagated(ref);
 	return trace.setSpanContext(base, ref);
 }
-function applyError(span, error) {
+function applyError(span, error, capture) {
 	const err = error instanceof Error ? error : void 0;
 	const errorType = err === void 0 ? "Error" : err.name !== "Error" && err.name.length > 0 ? err.name : (err.constructor?.name ?? "Error") || "Error";
-	const message = err?.message ?? String(error);
 	span.setStatus({ code: SpanStatusCode.ERROR });
 	span.setAttribute("error.type", errorType);
+	const captureContent = capture.captureInput && capture.captureOutput;
 	span.addEvent("exception", omitUndefined({
 		"exception.type": errorType,
-		"exception.message": message,
-		"exception.stacktrace": err?.stack,
+		"exception.message": captureContent ? prepareCaptureValue("exception.message", err?.message ?? String(error), capture) : void 0,
+		"exception.stacktrace": captureContent && err?.stack !== void 0 ? prepareCaptureValue("exception.stacktrace", err.stack, capture) : void 0,
 		"log.severity_number": SEVERITY_ERROR
 	}));
 }
@@ -593,7 +596,7 @@ function applyFields(span, meta, fields) {
 	if (fields.name) span.updateName(fields.name);
 	const attrs = fieldsToAttributes(fields, meta.type, meta.capture);
 	if (Object.keys(attrs).length > 0) span.setAttributes(attrs);
-	if (fields.error !== void 0) applyError(span, fields.error);
+	if (fields.error !== void 0) applyError(span, fields.error, meta.capture);
 }
 function metaFor(core, options) {
 	const cfg = core.config;
@@ -631,7 +634,7 @@ function createSpanHandle(core, name, options = {}) {
 	SPAN_META.set(span, meta);
 	if (Object.keys(attrs).length > 0) span.setAttributes(attrs);
 	if (options.name) span.updateName(options.name);
-	if (options.error !== void 0) applyError(span, options.error);
+	if (options.error !== void 0) applyError(span, options.error, meta.capture);
 	const spanContext = span.spanContext();
 	let previousOutputChunkTime;
 	const flags = (spanContext.traceFlags & 255).toString(16).padStart(2, "0");
@@ -682,6 +685,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.10",
   "description": "Pure TypeScript SDK for telemetry.dev: LLM traces, logs, and GenAI metrics on OpenTelemetry, for Node and edge runtimes.",
   "keywords": [
     "genai",
@@ -36,13 +36,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@opentelemetry/api-logs": "^0.218.0",
-    "@opentelemetry/core": "^2.7.1",
-    "@opentelemetry/resources": "^2.7.1",
-    "@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"
+    "@opentelemetry/api-logs": "^0.223.0",
+    "@opentelemetry/core": "^2.12.0",
+    "@opentelemetry/resources": "^2.12.0",
+    "@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"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",

package/src/capture.ts

@@ -270,8 +270,9 @@ export function prepareCaptureValue(
   if (cfg.mask) {
     try {
       masked = cfg.mask(value, { key });
-    } catch (error) {
-      reportError(cfg.onError, error instanceof Error ? error : new Error(String(error)));
+    } catch {
+      // Hook errors can contain the unmasked value or chain the application exception.
+      reportError(cfg.onError, new Error("mask hook raised; content dropped"));
 
       return undefined;
     }

package/src/client.ts

@@ -19,6 +19,7 @@ import {
   als,
   AlsContextManager,
   BATCHED_METRIC_INTERVAL_MS,
+  createExportFailures,
   createLogExporter,
   createMetricExporter,
   createMetricsPipeline,
@@ -156,7 +157,10 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     ...config.resourceAttributes,
   });
 
-  const transport: Transport = { fetchImpl: config.fetchImpl, onError: config.onError };
+  // A failed flush repeats the failure of its export, so the flush and the exporters share one
+  // failure state.
+  const failures = createExportFailures(config.onError);
+  const transport: Transport = { fetchImpl: config.fetchImpl, onError: config.onError, failures };
   const headers = config.apiKey ? otlpHeaders(config.apiKey, config.sdkName) : undefined;
 
   const spanExporter =
@@ -244,8 +248,8 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     if (!logs) {
       const logProcessor =
         config.exportMode === "immediate"
-          ? new SimpleLogRecordProcessor(logExporter)
-          : new BatchLogRecordProcessor(logExporter);
+          ? new SimpleLogRecordProcessor({ exporter: logExporter })
+          : new BatchLogRecordProcessor({ exporter: logExporter });
 
       const loggerProvider = new LoggerProvider({
         resource,
@@ -274,7 +278,7 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
 
     return Promise.all(parts)
       .then(() => undefined)
-      .catch((error: Error) => reportError(config.onError, error));
+      .catch((error: Error) => failures.report(error));
   };
 
   const handoff = (p: Promise<void>): Promise<void> => {

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`), including exception messages/stacks, before
+ * JSON stringification. Not applied to metadata or raw attributes.
+ */
 export type MaskFn<T = unknown> = (value: T, ctx: { key: string }) => T;
 
 export interface TelemetryOptions {
@@ -34,9 +38,9 @@ export interface TelemetryOptions {
   exportMode?: ExportMode;
   /** OTel sampling policy. Defaults to OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG. */
   sampler?: Sampler;
-  /** Capture span inputs (args, prompts) by default. Default true. */
+  /** Capture span inputs (args, prompts). False also omits exception messages/stacks. Default true. */
   captureInput?: boolean;
-  /** Capture span outputs (results, completions) by default. Default true. */
+  /** Capture span outputs (results, completions). False also omits exception messages/stacks. Default true. */
   captureOutput?: boolean;
   /** Redaction hook run on captured content before stringify/truncate. */
   mask?: MaskFn;
@@ -59,7 +63,7 @@ export interface TelemetryOptions {
   fetch?: typeof fetch;
   /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `flush()` does not await exports. */
   waitUntil?: (p: Promise<unknown>) => void;
-  /** Receives errors raised while emitting telemetry; repeated instrumentation failures from one stream may be coalesced into one report. The SDK never throws into user code. */
+  /** Receives errors raised while emitting telemetry; repeated instrumentation failures from one stream may be coalesced into one report. A series of failed exports is reported once, and the next failure after an export reaches the ingest is reported again. The SDK never throws into user code. */
   onError?: (cause: Error) => void;
   /** Header value for a custom telemetry.dev integration. */
   sdkName?: string;

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;
 }
 
@@ -143,7 +153,7 @@ function resolveParent(parent: ParentRef | undefined): Context {
   return trace.setSpanContext(base, ref);
 }
 
-function applyError(span: Span, error: unknown): void {
+function applyError(span: Span, error: unknown, capture: FieldCaptureConfig): void {
   const err = error instanceof Error ? error : undefined;
 
   // Prefer the specific subclass name (Python parity: type(error).__name__) — many SDK
@@ -155,15 +165,21 @@ function applyError(span: Span, error: unknown): void {
         ? err.name
         : (err.constructor?.name ?? "Error") || "Error";
 
-  const message = err?.message ?? String(error);
   span.setStatus({ code: SpanStatusCode.ERROR });
   span.setAttribute("error.type", errorType);
+  // Exceptions can echo either inputs or outputs; both must allow content capture.
+  const captureContent = capture.captureInput && capture.captureOutput;
   span.addEvent(
     "exception",
     omitUndefined({
       "exception.type": errorType,
-      "exception.message": message,
-      "exception.stacktrace": err?.stack,
+      "exception.message": captureContent
+        ? prepareCaptureValue("exception.message", err?.message ?? String(error), capture)
+        : undefined,
+      "exception.stacktrace":
+        captureContent && err?.stack !== undefined
+          ? prepareCaptureValue("exception.stacktrace", err.stack, capture)
+          : undefined,
       "log.severity_number": SEVERITY_ERROR,
     }),
   );
@@ -175,7 +191,7 @@ function applyFields(span: Span, meta: SpanMeta, fields: SpanFields): void {
 
   if (Object.keys(attrs).length > 0) span.setAttributes(attrs);
 
-  if (fields.error !== undefined) applyError(span, fields.error);
+  if (fields.error !== undefined) applyError(span, fields.error, meta.capture);
 }
 
 function metaFor(core: ClientCore, options?: StartSpanOptions): SpanMeta {
@@ -236,7 +252,7 @@ export function createSpanHandle(
 
   if (options.name) span.updateName(options.name);
 
-  if (options.error !== undefined) applyError(span, options.error);
+  if (options.error !== undefined) applyError(span, options.error, meta.capture);
 
   const spanContext = span.spanContext();
   let previousOutputChunkTime: number | undefined;
@@ -303,6 +319,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);