@telemetry-dev/sdk 0.1.6 → 0.1.8

package/README.md

@@ -55,11 +55,21 @@ Without an API key every call is a silent no-op — the SDK never throws into yo
 
 Other `init()` options: `enabled` (kill switch), `registerGlobal`, `exportMode: "batched" |
 "immediate"`, `captureInput` / `captureOutput`, `mask(value, { key })` redaction hook,
-`maxAttributeLength` (default 65536, truncated values end with `...[truncated]`), `batch`
+`maxAttributeLength` (a non-negative safe integer or `Infinity`; default 65536; `null` and
+`undefined` select the default, while other invalid values disable telemetry and are reported
+through `onError`; truncated values use `...[truncated]`, or its prefix when the cap is shorter than
+the marker; the cap also applies, with the marker, to string metadata and log attributes, and any
+other string attribute is cut at the cap without a marker, except that a cap of `0` leaves those at
+65536), `batch`
 (`maxExportBatchSize` 64, `scheduledDelayMillis` 1000, `maxQueueSize` 2048,
 `exportTimeoutMillis` 30000), `spanFilter`, `resourceAttributes`, `logLevel` (SDK diagnostics,
 default `"warn"`), `fetch`, `waitUntil`, `onError`.
 
+`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.
+
 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.
@@ -92,6 +102,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.
@@ -115,9 +127,13 @@ after the ended span passes `spanFilter`, including interrupted streams. Chunk t
 histogram state and does not retain individual intervals. Pull-based timing includes consumer delay
 between reads. An explicit timestamp uses the same monotonic millisecond clock for every chunk.
 
-Provider integrations feature-detect chunk recording. With an older core SDK that lacks
-`recordOutputChunk`, streams and existing tracing continue normally, but chunk-interval metrics are
-unavailable. Upgrade the core SDK with provider integrations to enable the new metric.
+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. 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.
 
 ## Serverless
 

package/dist/index.d.mts

@@ -34,7 +34,7 @@ interface TelemetryOptions {
   captureOutput?: boolean;
   /** Redaction hook run on captured content before stringify/truncate. */
   mask?: MaskFn;
-  /** Truncation cap (chars) for content attributes; also set as the provider's attributeValueLengthLimit. Default 65536. */
+  /** Non-negative safe-integer truncation cap for content attributes; Infinity disables truncation. The cap also applies, with the marker, to string metadata and log attributes; any other string attribute is cut at the cap without a marker, except that a cap of 0 leaves those at 65536. init() reports invalid values through onError and returns a disabled client. Default 65536. */
   maxAttributeLength?: number;
   batch?: BatchOptions$1;
   /** Export filter. Default when registerGlobal: only spans from this SDK's instrumentation scope. */
@@ -53,7 +53,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 any error raised while emitting telemetry; 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. The SDK never throws into user code. */
   onError?: (cause: Error) => void;
   /** Header value for a custom telemetry.dev integration. */
   sdkName?: string;
@@ -154,6 +154,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;
@@ -189,6 +191,11 @@ interface StartSpanOptions extends SpanFields {
   /** Per-call override of the global captureOutput. */
   captureOutput?: boolean;
 }
+interface SpanCapturePolicy {
+  readonly output: boolean;
+  readonly mask: boolean;
+  readonly maxAttributeLength: number;
+}
 interface SpanHandle {
   /** Raw OTel span (interop escape hatch). */
   readonly span: Span;
@@ -199,9 +206,11 @@ interface SpanHandle {
   /** W3C traceparent for this span; null for the no-op handle. */
   readonly traceparent: string | null;
   readonly isRecording: boolean;
+  readonly capturePolicy?: SpanCapturePolicy;
   update(fields: SpanFields): SpanHandle;
   /** Records an output chunk arrival. Pull-based streams include consumer delay between pulls. */
   recordOutputChunk(timestampMs?: number): void;
+  reportError?(cause: unknown): void;
   end(fields?: SpanFields & {
     endTime?: Date | number;
   }): void;
@@ -235,4 +244,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 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

@@ -5,9 +5,13 @@ import { BatchLogRecordProcessor, LoggerProvider, SimpleLogRecordProcessor } fro
 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 { SeverityNumber } from "@opentelemetry/api-logs";
+//#region src/config.ts
+const DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536;
 function resolveConfig(options = {}) {
 	const env = resolveEnv();
 	if (options.sessionMode !== void 0 && options.sessionMode !== "explicit" && options.sessionMode !== "process") throw new TypeError(`Invalid sessionMode: ${String(options.sessionMode)}`);
+	const maxAttributeLength = options.maxAttributeLength == null ? DEFAULT_MAX_ATTRIBUTE_LENGTH : options.maxAttributeLength;
+	if (maxAttributeLength !== Number.POSITIVE_INFINITY && (!Number.isSafeInteger(maxAttributeLength) || maxAttributeLength < 0)) throw new RangeError("maxAttributeLength must be a non-negative safe integer or Infinity");
 	const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 	return {
 		apiKey: options.apiKey ?? env.TELEMETRY_DEV_API_KEY,
@@ -22,7 +26,7 @@ function resolveConfig(options = {}) {
 		captureInput: options.captureInput ?? true,
 		captureOutput: options.captureOutput ?? true,
 		mask: options.mask,
-		maxAttributeLength: options.maxAttributeLength ?? 65536,
+		maxAttributeLength,
 		batch: {
 			...DEFAULT_BATCH,
 			...options.batch
@@ -45,6 +49,13 @@ const NOOP_CLIENT = {
 	shutdown: () => Promise.resolve()
 };
 let activeClient;
+function shutdownClient(client, onError) {
+	try {
+		client.shutdown().catch((error) => reportError(onError, error));
+	} catch (error) {
+		reportError(onError, error instanceof Error ? error : new Error(String(error)));
+	}
+}
 function currentClient() {
 	return activeClient ?? NOOP_CLIENT;
 }
@@ -52,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();
 }
@@ -59,20 +74,22 @@ function shutdown() {
 	return currentClient().shutdown();
 }
 function init(options, overrides) {
+	const previousClient = activeClient;
 	try {
+		setLogLevel(options?.logLevel ?? "warn");
 		return initInner(options, overrides);
 	} catch (error) {
 		reportError(options?.onError, error instanceof Error ? error : new Error(String(error)));
-		activeClient = NOOP_CLIENT;
+		if (previousClient && previousClient !== NOOP_CLIENT) shutdownClient(previousClient, options?.onError);
+		if (activeClient === previousClient) activeClient = NOOP_CLIENT;
 		return NOOP_CLIENT;
 	}
 }
 function initInner(options, overrides) {
 	const config = resolveConfig(options);
-	setLogLevel(config.logLevel);
 	if (activeClient && activeClient !== NOOP_CLIENT) {
 		diag.warn("init() called again; replacing the previous client");
-		activeClient.shutdown().catch((error) => reportError(config.onError, error));
+		shutdownClient(activeClient, config.onError);
 	}
 	if (!(config.enabled && Boolean(config.apiKey ?? overrides?.spanExporter))) {
 		if (config.enabled && !config.apiKey) diag.debug("no api key (apiKey option or TELEMETRY_DEV_API_KEY); telemetry disabled");
@@ -112,11 +129,12 @@ function initInner(options, overrides) {
 		recordMetrics: metrics ? (span) => metrics.record(span) : void 0,
 		onError: config.onError
 	});
+	const backstopLength = config.maxAttributeLength || 65536;
 	const provider = new BasicTracerProvider({
 		resource,
 		sampler: sessionSampler(config.sampler),
 		spanProcessors: [processor],
-		spanLimits: { attributeValueLengthLimit: config.maxAttributeLength }
+		spanLimits: { attributeValueLengthLimit: backstopLength }
 	});
 	const tracer = provider.getTracer(SCOPE_NAME$1, SCOPE_VERSION);
 	let registeredTrace = false;
@@ -139,7 +157,7 @@ function initInner(options, overrides) {
 			const logProcessor = config.exportMode === "immediate" ? new SimpleLogRecordProcessor(logExporter) : new BatchLogRecordProcessor(logExporter);
 			const loggerProvider = new LoggerProvider({
 				resource,
-				logRecordLimits: { attributeValueLengthLimit: config.maxAttributeLength },
+				logRecordLimits: { attributeValueLengthLimit: backstopLength },
 				processors: [logProcessor]
 			});
 			logs = {
@@ -295,7 +313,13 @@ function boundedCaptureDetails(input, options = {}) {
 				const converted = visit(item, depth + 1, [...path, key]);
 				if (converted === void 0) bytes = previousBytes;
 				else {
-					result[key] = converted;
+					if (key === "__proto__") Object.defineProperty(result, key, {
+						configurable: true,
+						enumerable: true,
+						value: converted,
+						writable: true
+					});
+					else result[key] = converted;
 					emitted = true;
 				}
 			}
@@ -323,7 +347,9 @@ function boundedCapture(input, options = {}) {
 }
 function truncate(value, maxLength) {
 	if (value.length <= maxLength) return value;
-	return value.slice(0, Math.max(maxLength - 14, 0)) + TRUNCATION_MARKER;
+	const limit = Math.max(maxLength, 0);
+	const marker = TRUNCATION_MARKER.slice(0, limit);
+	return value.slice(0, limit - marker.length) + marker;
 }
 /** The single content funnel: mask → JSON stringify → truncate. */
 function prepareCaptureValue(key, value, cfg) {
@@ -506,8 +532,14 @@ const NOOP_SPAN_HANDLE = {
 	spanId: INVALID_SPAN_CONTEXT.spanId,
 	traceparent: null,
 	isRecording: false,
+	capturePolicy: {
+		output: false,
+		mask: false,
+		maxAttributeLength: 0
+	},
 	update: () => NOOP_SPAN_HANDLE,
 	recordOutputChunk: () => {},
+	reportError: () => {},
 	end: () => {}
 };
 //#endregion
@@ -609,6 +641,11 @@ function createSpanHandle(core, name, options = {}) {
 		traceId: spanContext.traceId,
 		spanId: spanContext.spanId,
 		traceparent: `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`,
+		capturePolicy: {
+			output: meta.capture.captureOutput,
+			mask: meta.capture.mask !== void 0,
+			maxAttributeLength: meta.capture.maxAttributeLength
+		},
 		get isRecording() {
 			return span.isRecording();
 		},
@@ -642,6 +679,9 @@ function createSpanHandle(core, name, options = {}) {
 			}
 			previousOutputChunkTime = now;
 		},
+		reportError(cause) {
+			reportError(meta.onError, cause instanceof Error ? cause : new Error(String(cause)));
+		},
 		end(fields) {
 			try {
 				if (fields) applyFields(span, meta, fields);
@@ -769,4 +809,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.6",
+  "version": "0.1.8",
   "description": "Pure TypeScript SDK for telemetry.dev: LLM traces, logs, and GenAI metrics on OpenTelemetry, for Node and edge runtimes.",
   "keywords": [
     "genai",

package/src/capture.ts

@@ -168,7 +168,7 @@ export function boundedCaptureDetails(
         return result;
       }
 
-      const result: CapturedObject = {};
+      const result = {} as CapturedObject;
       let emitted = false;
 
       for (const key in value) {
@@ -213,7 +213,17 @@ export function boundedCaptureDetails(
         if (converted === undefined) {
           bytes = previousBytes;
         } else {
-          result[key] = converted;
+          if (key === "__proto__") {
+            Object.defineProperty(result, key, {
+              configurable: true,
+              enumerable: true,
+              value: converted,
+              writable: true,
+            });
+          } else {
+            result[key] = converted;
+          }
+
           emitted = true;
         }
       }
@@ -243,9 +253,10 @@ export function boundedCapture(
 export function truncate(value: string, maxLength: number): string {
   if (value.length <= maxLength) return value;
 
-  // Total stays within maxLength so the provider's attributeValueLengthLimit backstop
-  // (set to the same cap) never slices the marker off.
-  return value.slice(0, Math.max(maxLength - TRUNCATION_MARKER.length, 0)) + TRUNCATION_MARKER;
+  const limit = Math.max(maxLength, 0);
+  const marker = TRUNCATION_MARKER.slice(0, limit);
+
+  return value.slice(0, limit - marker.length) + marker;
 }
 
 /** The single content funnel: mask → JSON stringify → truncate. */

package/src/client.ts

@@ -36,7 +36,12 @@ import {
   type Transport,
 } from "@telemetry-dev/otel";
 
-import { type ResolvedConfig, resolveConfig, type TelemetryOptions } from "./config.ts";
+import {
+  DEFAULT_MAX_ATTRIBUTE_LENGTH,
+  type ResolvedConfig,
+  resolveConfig,
+  type TelemetryOptions,
+} from "./config.ts";
 
 /** Test seam: inject in-memory exporters instead of the OTLP fetch transport. */
 export interface ClientOverrides {
@@ -71,6 +76,14 @@ const NOOP_CLIENT: ClientHandle = {
 
 let activeClient: ClientHandle | undefined;
 
+function shutdownClient(client: ClientHandle, onError?: (cause: Error) => void): void {
+  try {
+    void client.shutdown().catch((error: Error) => reportError(onError, error));
+  } catch (error) {
+    reportError(onError, error instanceof Error ? error : new Error(String(error)));
+  }
+}
+
 export function currentClient(): ClientHandle {
   return activeClient ?? NOOP_CLIENT;
 }
@@ -81,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();
 }
@@ -90,11 +108,20 @@ export function shutdown(): Promise<void> {
 }
 
 export function init(options?: TelemetryOptions, overrides?: ClientOverrides): TelemetryClient {
+  const previousClient = activeClient;
+
   try {
+    setLogLevel(options?.logLevel ?? "warn");
+
     return initInner(options, overrides);
   } catch (error) {
     reportError(options?.onError, error instanceof Error ? error : new Error(String(error)));
-    activeClient = NOOP_CLIENT;
+
+    if (previousClient && previousClient !== NOOP_CLIENT) {
+      shutdownClient(previousClient, options?.onError);
+    }
+
+    if (activeClient === previousClient) activeClient = NOOP_CLIENT;
 
     return NOOP_CLIENT;
   }
@@ -102,12 +129,11 @@ export function init(options?: TelemetryOptions, overrides?: ClientOverrides): T
 
 function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): TelemetryClient {
   const config = resolveConfig(options);
-  setLogLevel(config.logLevel);
 
   if (activeClient && activeClient !== NOOP_CLIENT) {
     diag.warn("init() called again; replacing the previous client");
     // shutdown() synchronously releases global registrations before this init claims them.
-    void activeClient.shutdown().catch((error: Error) => reportError(config.onError, error));
+    shutdownClient(activeClient, config.onError);
   }
 
   const enabled = config.enabled && Boolean(config.apiKey ?? overrides?.spanExporter);
@@ -167,11 +193,14 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     onError: config.onError,
   });
 
+  // A zero cap only drops content; OpenTelemetry rejects it as a provider limit.
+  const backstopLength = config.maxAttributeLength || DEFAULT_MAX_ATTRIBUTE_LENGTH;
+
   const provider = new BasicTracerProvider({
     resource,
     sampler: sessionSampler(config.sampler),
     spanProcessors: [processor],
-    spanLimits: { attributeValueLengthLimit: config.maxAttributeLength },
+    spanLimits: { attributeValueLengthLimit: backstopLength },
   });
 
   const tracer = provider.getTracer(SCOPE_NAME, SCOPE_VERSION);
@@ -220,7 +249,7 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
 
       const loggerProvider = new LoggerProvider({
         resource,
-        logRecordLimits: { attributeValueLengthLimit: config.maxAttributeLength },
+        logRecordLimits: { attributeValueLengthLimit: backstopLength },
         processors: [logProcessor],
       });
 

package/src/config.ts

@@ -40,7 +40,7 @@ export interface TelemetryOptions {
   captureOutput?: boolean;
   /** Redaction hook run on captured content before stringify/truncate. */
   mask?: MaskFn;
-  /** Truncation cap (chars) for content attributes; also set as the provider's attributeValueLengthLimit. Default 65536. */
+  /** Non-negative safe-integer truncation cap for content attributes; Infinity disables truncation. The cap also applies, with the marker, to string metadata and log attributes; any other string attribute is cut at the cap without a marker, except that a cap of 0 leaves those at 65536. init() reports invalid values through onError and returns a disabled client. Default 65536. */
   maxAttributeLength?: number;
   batch?: BatchOptions;
   /** Export filter. Default when registerGlobal: only spans from this SDK's instrumentation scope. */
@@ -59,7 +59,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 any error raised while emitting telemetry; 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. The SDK never throws into user code. */
   onError?: (cause: Error) => void;
   /** Header value for a custom telemetry.dev integration. */
   sdkName?: string;
@@ -104,6 +104,16 @@ export function resolveConfig(options: TelemetryOptions = {}): ResolvedConfig {
     throw new TypeError(`Invalid sessionMode: ${String(options.sessionMode)}`);
   }
 
+  const maxAttributeLength =
+    options.maxAttributeLength == null ? DEFAULT_MAX_ATTRIBUTE_LENGTH : options.maxAttributeLength;
+
+  if (
+    maxAttributeLength !== Number.POSITIVE_INFINITY &&
+    (!Number.isSafeInteger(maxAttributeLength) || maxAttributeLength < 0)
+  ) {
+    throw new RangeError("maxAttributeLength must be a non-negative safe integer or Infinity");
+  }
+
   const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(
     /\/+$/,
     "",
@@ -122,7 +132,7 @@ export function resolveConfig(options: TelemetryOptions = {}): ResolvedConfig {
     captureInput: options.captureInput ?? true,
     captureOutput: options.captureOutput ?? true,
     mask: options.mask,
-    maxAttributeLength: options.maxAttributeLength ?? DEFAULT_MAX_ATTRIBUTE_LENGTH,
+    maxAttributeLength,
     batch: { ...DEFAULT_BATCH, ...options.batch },
     spanFilter: options.spanFilter,
     sessionRootOf: options.sessionRootOf,

package/src/index.ts

@@ -9,6 +9,7 @@ export type {
 
 export {
   captureEnabled,
+  captureMasked,
   type ClientOverrides,
   flush,
   init,
@@ -51,6 +52,7 @@ export {
   getTraceparent,
   injectW3cContext,
   type ParentRef,
+  type SpanCapturePolicy,
   type SpanHandle,
   startActiveSpan,
   startSpan,

package/src/noop.ts

@@ -12,7 +12,9 @@ export const NOOP_SPAN_HANDLE: SpanHandle = {
   spanId: INVALID_SPAN_CONTEXT.spanId,
   traceparent: null,
   isRecording: false,
+  capturePolicy: { output: false, mask: false, maxAttributeLength: 0 },
   update: () => NOOP_SPAN_HANDLE,
   recordOutputChunk: () => {},
+  reportError: () => {},
   end: () => {},
 };

package/src/span.ts

@@ -59,6 +59,12 @@ export interface StartSpanOptions extends SpanFields {
   captureOutput?: boolean;
 }
 
+export interface SpanCapturePolicy {
+  readonly output: boolean;
+  readonly mask: boolean;
+  readonly maxAttributeLength: number;
+}
+
 export interface SpanHandle {
   /** Raw OTel span (interop escape hatch). */
   readonly span: Span;
@@ -69,9 +75,11 @@ export interface SpanHandle {
   /** W3C traceparent for this span; null for the no-op handle. */
   readonly traceparent: string | null;
   readonly isRecording: boolean;
+  readonly capturePolicy?: SpanCapturePolicy;
   update(fields: SpanFields): SpanHandle;
   /** Records an output chunk arrival. Pull-based streams include consumer delay between pulls. */
   recordOutputChunk(timestampMs?: number): void;
+  reportError?(cause: unknown): void;
   end(fields?: SpanFields & { endTime?: Date | number }): void;
 }
 
@@ -240,6 +248,11 @@ export function createSpanHandle(
     traceId: spanContext.traceId,
     spanId: spanContext.spanId,
     traceparent: `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`,
+    capturePolicy: {
+      output: meta.capture.captureOutput,
+      mask: meta.capture.mask !== undefined,
+      maxAttributeLength: meta.capture.maxAttributeLength,
+    },
     get isRecording() {
       return span.isRecording();
     },
@@ -287,6 +300,9 @@ export function createSpanHandle(
 
       previousOutputChunkTime = now;
     },
+    reportError(cause) {
+      reportError(meta.onError, cause instanceof Error ? cause : new Error(String(cause)));
+    },
     end(fields) {
       try {
         if (fields) applyFields(span, meta, fields);