@mastra/observability 1.16.6 → 1.17.0-alpha.1

package/dist/index.js

@@ -10,6 +10,7 @@ import path from "path";
 import { TransformStream } from "stream/web";
 import { coreFeatures } from "@mastra/core/features";
 import { buildCreateSpanRecord, buildFeedbackRecord, buildLogRecord, buildMetricRecord, buildScoreRecord, buildUpdateSpanRecord } from "@mastra/core/storage";
+import { createHash } from "crypto";
 //#region src/bus/route-event.ts
 /**
 * Route a single event to the appropriate method on a handler.
@@ -745,7 +746,11 @@ const observabilityConfigValueSchema = z.object(observabilityInstanceConfigField
 const sensitiveDataFilterOptionsSchema = z.object({
 	sensitiveFields: z.array(z.string()).optional(),
 	redactionToken: z.string().optional(),
-	redactionStyle: z.enum(["full", "partial"]).optional()
+	redactionStyle: z.enum([
+		"full",
+		"partial",
+		"indexed"
+	]).optional()
 }).strict();
 const observabilityRegistryConfigSchema = z.object({
 	default: z.object({ enabled: z.boolean().optional() }).optional().nullable(),
@@ -2516,8 +2521,10 @@ var BaseSpan = class {
 	entityId;
 	/** Entity name that created the span */
 	entityName;
-	/** Parent span ID (for root spans that are children of external spans) */
+	/** Parent span within this Mastra trace: a span Mastra created (the span-tree parent, or a prior Mastra span such as the suspended run a resume links back to) */
 	parentSpanId;
+	/** Parent from an external tracing system (ambient OTel / dd-trace span) that Mastra did not create; carried for external correlation, not part of Mastra's own parent/child linkage */
+	externalParentSpanId;
 	/** Deep clean options for serialization */
 	deepCleanOptions;
 	/**
@@ -2624,6 +2631,17 @@ var BaseSpan = class {
 		if (parentSpan) return parentSpan.id;
 		return this.parent.getParentSpanId(includeInternalSpans);
 	}
+	/**
+	* External (foreign tracing-system) parent id to export alongside
+	* {@link getParentSpanId}. When every Mastra ancestor is dropped from
+	* export, the span is exported at the root's position, so the root's
+	* external parent must travel with it.
+	*/
+	getExportedExternalParentSpanId(includeInternalSpans) {
+		if (!this.parent) return this.externalParentSpanId;
+		if (this.getParentSpan(includeInternalSpans)) return this.externalParentSpanId;
+		return this.parent.getExportedExternalParentSpanId(includeInternalSpans);
+	}
 	/** Find the closest parent span of a specific type by walking up the parent chain */
 	findParent(spanType) {
 		let current = this.parent;
@@ -2698,6 +2716,7 @@ var BaseSpan = class {
 			isEvent: this.isEvent,
 			isRootSpan: this.isRootSpan,
 			parentSpanId: this.getParentSpanId(includeInternalSpans),
+			externalParentSpanId: this.getExportedExternalParentSpanId(includeInternalSpans),
 			...this.isRootSpan && this.tags?.length ? { tags: this.tags } : {}
 		};
 	}
@@ -2740,6 +2759,7 @@ var DefaultSpan = class extends BaseSpan {
 			this.id = options.spanId;
 			this.traceId = options.traceId;
 			if (options.parentSpanId) this.parentSpanId = options.parentSpanId;
+			if (options.externalParentSpanId) this.externalParentSpanId = options.externalParentSpanId;
 			return;
 		}
 		const bridge = observabilityInstance.getBridge();
@@ -2748,7 +2768,8 @@ var DefaultSpan = class extends BaseSpan {
 			if (bridgeIds) {
 				this.id = bridgeIds.spanId;
 				this.traceId = bridgeIds.traceId;
-				this.parentSpanId = bridgeIds.parentSpanId;
+				this.parentSpanId = options.parentSpanId ?? bridgeIds.parentSpanId;
+				this.externalParentSpanId = options.externalParentSpanId ?? bridgeIds.externalParentSpanId;
 				return;
 			}
 		}
@@ -2762,6 +2783,8 @@ var DefaultSpan = class extends BaseSpan {
 		this.id = generateSpanId();
 		if (options.parentSpanId) if (isValidSpanId(options.parentSpanId)) this.parentSpanId = options.parentSpanId;
 		else console.error(`[Mastra Tracing] Invalid parentSpanId: must be 1-16 hexadecimal characters, got "${options.parentSpanId}". Ignoring.`);
+		if (options.externalParentSpanId) if (isValidSpanId(options.externalParentSpanId)) this.externalParentSpanId = options.externalParentSpanId;
+		else console.error(`[Mastra Tracing] Invalid externalParentSpanId: must be 1-16 hexadecimal characters, got "${options.externalParentSpanId}". Ignoring.`);
 	}
 	end(options) {
 		if (this.isEvent) return;
@@ -3010,11 +3033,13 @@ var BaseObservabilityInstance = class extends MastraBase {
 		} : enrichedMetadata;
 		const tags = !options.parent ? tracingOptions?.tags : void 0;
 		const traceId = !options.parent ? options.traceId ?? tracingOptions?.traceId : options.traceId;
-		const parentSpanId = !options.parent ? options.parentSpanId ?? tracingOptions?.parentSpanId : options.parentSpanId;
+		const parentSpanId = options.parentSpanId;
+		const externalParentSpanId = !options.parent ? options.externalParentSpanId ?? tracingOptions?.parentSpanId : options.externalParentSpanId;
 		const span = this.createSpan({
 			...rest,
 			traceId,
 			parentSpanId,
+			externalParentSpanId,
 			metadata: finalMetadata,
 			traceState,
 			tags,
@@ -8703,13 +8728,26 @@ var ObservabilityRegistry = class {
 //#endregion
 //#region src/span_processors/sensitive-data-filter.ts
 /**
+* Maximum number of traces to keep indexed-redaction state for.
+* Spans never signal trace completion, so state is evicted least-recently-used.
+*/
+const MAX_TRACKED_TRACES = 1e3;
+/**
+* Maximum number of unique values tracked per trace for indexed redaction.
+* Once reached, new values fall back to the full redaction token while
+* already-tracked values keep their assigned tokens.
+*/
+const MAX_TRACKED_VALUES_PER_TRACE = 1e3;
+/**
 * SensitiveDataFilter
 *
 * An SpanOutputProcessor that redacts sensitive information from span fields.
 *
 * - Sensitive keys are matched case-insensitively, normalized to remove separators.
-* - Sensitive values are redacted using either full or partial redaction.
+* - Sensitive values are redacted using full, partial, or indexed redaction.
 * - Partial redaction always keeps 3 chars at the start and end.
+* - Indexed redaction assigns each unique value a stable `[LABEL_N]` token,
+*   consistent across all spans of a trace.
 * - JSON strings containing sensitive fields are parsed and redacted.
 * - If filtering a field fails, the field is replaced with:
 *   `{ error: { processor: "sensitive-data-filter" } }`
@@ -8719,6 +8757,7 @@ var SensitiveDataFilter = class {
 	sensitiveFields;
 	redactionToken;
 	redactionStyle;
+	traceStates = /* @__PURE__ */ new Map();
 	constructor(options = {}) {
 		this.sensitiveFields = (options.sensitiveFields || [
 			"password",
@@ -8748,42 +8787,63 @@ var SensitiveDataFilter = class {
 	* @returns A new span with sensitive values redacted
 	*/
 	process(span) {
-		span.attributes = this.tryFilter(span.attributes);
-		span.metadata = this.tryFilter(span.metadata);
-		span.input = this.tryFilter(span.input);
-		span.output = this.tryFilter(span.output);
-		span.errorInfo = this.tryFilter(span.errorInfo);
+		const indexedState = this.redactionStyle === "indexed" ? this.getTraceState(span.traceId) : void 0;
+		span.attributes = this.tryFilter(span.attributes, indexedState);
+		span.metadata = this.tryFilter(span.metadata, indexedState);
+		span.input = this.tryFilter(span.input, indexedState);
+		span.output = this.tryFilter(span.output, indexedState);
+		span.errorInfo = this.tryFilter(span.errorInfo, indexedState);
 		return span;
 	}
 	/**
+	* Get (or create) the indexed-redaction state for a trace.
+	* Uses the Map's insertion order as an LRU: accessed traces are re-inserted,
+	* and the least recently used trace is evicted once the cap is exceeded.
+	*/
+	getTraceState(traceId) {
+		let state = this.traceStates.get(traceId);
+		if (state) this.traceStates.delete(traceId);
+		else state = {
+			tokensByValue: /* @__PURE__ */ new Map(),
+			counters: /* @__PURE__ */ new Map()
+		};
+		this.traceStates.set(traceId, state);
+		while (this.traceStates.size > MAX_TRACKED_TRACES) {
+			const oldest = this.traceStates.keys().next().value;
+			if (oldest === void 0) break;
+			this.traceStates.delete(oldest);
+		}
+		return state;
+	}
+	/**
 	* Recursively filter objects/arrays for sensitive keys.
 	* Handles circular references by replacing with a marker.
 	* Also attempts to parse and redact JSON strings.
 	*/
-	deepFilter(obj, seen = /* @__PURE__ */ new WeakSet()) {
+	deepFilter(obj, seen = /* @__PURE__ */ new WeakSet(), indexedState) {
 		if (obj === null || typeof obj !== "object") {
 			if (typeof obj === "string") {
 				const trimmed = obj.trim();
-				if (trimmed.startsWith("{") || trimmed.startsWith("[")) return this.redactJsonString(obj);
+				if (trimmed.startsWith("{") || trimmed.startsWith("[")) return this.redactJsonString(obj, indexedState);
 			}
 			return obj;
 		}
 		if (seen.has(obj)) return "[Circular Reference]";
 		seen.add(obj);
 		if (obj instanceof Date) return obj;
-		if (Array.isArray(obj)) return obj.map((item) => this.deepFilter(item, seen));
+		if (Array.isArray(obj)) return obj.map((item) => this.deepFilter(item, seen, indexedState));
 		const filtered = {};
 		for (const key of Object.keys(obj)) {
 			const normKey = this.normalizeKey(key);
-			if (this.isSensitive(normKey)) if (obj[key] && typeof obj[key] === "object") filtered[key] = this.deepFilter(obj[key], seen);
-			else filtered[key] = this.redactValue(obj[key]);
-			else filtered[key] = this.deepFilter(obj[key], seen);
+			if (this.isSensitive(normKey)) if (obj[key] && typeof obj[key] === "object") filtered[key] = this.deepFilter(obj[key], seen, indexedState);
+			else filtered[key] = this.redactValue(obj[key], normKey, indexedState);
+			else filtered[key] = this.deepFilter(obj[key], seen, indexedState);
 		}
 		return filtered;
 	}
-	tryFilter(value) {
+	tryFilter(value, indexedState) {
 		try {
-			return this.deepFilter(value);
+			return this.deepFilter(value, /* @__PURE__ */ new WeakSet(), indexedState);
 		} catch {
 			return { error: { processor: this.name } };
 		}
@@ -8813,11 +8873,11 @@ var SensitiveDataFilter = class {
 	* Attempt to parse a string as JSON and redact sensitive fields within it.
 	* If parsing fails or no sensitive data is found, returns the original string.
 	*/
-	redactJsonString(str) {
+	redactJsonString(str, indexedState) {
 		try {
 			const parsed = JSON.parse(str);
 			if (parsed && typeof parsed === "object") {
-				const filtered = this.deepFilter(parsed, /* @__PURE__ */ new WeakSet());
+				const filtered = this.deepFilter(parsed, /* @__PURE__ */ new WeakSet(), indexedState);
 				return JSON.stringify(filtered);
 			}
 			return str;
@@ -8829,17 +8889,36 @@ var SensitiveDataFilter = class {
 	* Redact a sensitive value.
 	* - Full style: replaces with a fixed token.
 	* - Partial style: shows 3 chars at start and end, hides the middle.
+	* - Indexed style: replaces with a stable `[LABEL_N]` token, where the label
+	*   comes from the normalized field name and the same value always maps to
+	*   the same token within a trace.
 	*
-	* Non-string values are converted to strings before partial redaction.
-	*/
-	redactValue(value) {
-		if (this.redactionStyle === "full") return this.redactionToken;
-		const str = String(value);
-		const len = str.length;
-		if (len <= 6) return this.redactionToken;
-		return str.slice(0, 3) + "…" + str.slice(len - 3);
+	* Non-string values are converted to strings before partial or indexed redaction.
+	*/
+	redactValue(value, normKey, indexedState) {
+		if (this.redactionStyle === "partial") {
+			const str = String(value);
+			const len = str.length;
+			if (len <= 6) return this.redactionToken;
+			return str.slice(0, 3) + "…" + str.slice(len - 3);
+		}
+		if (this.redactionStyle === "indexed" && indexedState) {
+			const valueKey = createHash("sha256").update(String(value)).digest("hex");
+			const existing = indexedState.tokensByValue.get(valueKey);
+			if (existing) return existing;
+			if (indexedState.tokensByValue.size >= MAX_TRACKED_VALUES_PER_TRACE) return this.redactionToken;
+			const label = normKey.toUpperCase();
+			const count = (indexedState.counters.get(label) ?? 0) + 1;
+			indexedState.counters.set(label, count);
+			const token = `[${label}_${count}]`;
+			indexedState.tokensByValue.set(valueKey, token);
+			return token;
+		}
+		return this.redactionToken;
+	}
+	async shutdown() {
+		this.traceStates.clear();
 	}
-	async shutdown() {}
 };
 //#endregion
 //#region src/default.ts