@telemetry-dev/sdk 0.1.9 → 0.1.10

package/README.md

@@ -78,16 +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`. `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.
+`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.

package/dist/index.d.mts

@@ -7,8 +7,8 @@ import { PushMetricExporter } from "@opentelemetry/sdk-metrics";
 //#region src/config.d.ts
 /**
  * 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.
+ * 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;
@@ -32,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;
@@ -57,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;

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);
+	} catch {
+		reportError(cfg.onError, /* @__PURE__ */ new Error("mask hook raised; content dropped"));
 		return;
 	}
 	const serialized = jsonAttr(masked);
@@ -577,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
 	}));
 }
@@ -594,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;
@@ -632,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");

package/package.json

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

@@ -14,8 +14,8 @@ export type { BatchOptions, ExportMode, LogLevel, SdkLogLevel } from "@telemetry
 
 /**
  * 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.
+ * 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;
 
@@ -38,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;
@@ -63,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/span.ts

@@ -153,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
@@ -165,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,
     }),
   );
@@ -185,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 {
@@ -246,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;