@mastra/observability 1.21.0 → 1.21.1-alpha.1

package/dist/index.js

@@ -2193,6 +2193,9 @@ function isDefined(value) {
 * - Google/Gemini: cachedContentTokenCount, thoughtsTokenCount in providerMetadata.google.usageMetadata
 * - OpenRouter: Uses OpenAI-compatible structure (cache tokens in usage)
 *
+* Kept in sync with `packages/core/src/observability/usage.ts` (duplicated so exporters do not need a newer core).
+* Change both copies together; `usage.parity.test.ts` fails if they drift.
+*
 * @param usage - The LanguageModelV2Usage from AI SDK response
 * @param providerMetadata - Optional provider-specific metadata
 * @returns UsageStats with inputDetails and outputDetails
@@ -2638,7 +2641,7 @@ var ModelSpanTracker = class {
 	* Returns undefined if no step span is active.
 	*/
 	exportCurrentStep() {
-		return this.#currentStepSpan?.exportSpan();
+		return this.#currentStepSpan?.snapshot();
 	}
 	/**
 	* Get the pending step finish payload (captured when defer mode is enabled).
@@ -3169,6 +3172,28 @@ function mergeMetadata$1(parentMetadata, metadata) {
 }
 //#endregion
 //#region src/spans/base.ts
+const LINEAGE_KEYS = [
+	"parentEntityType",
+	"parentEntityId",
+	"parentEntityName",
+	"parentEntityVersionId",
+	"rootEntityType",
+	"rootEntityId",
+	"rootEntityName",
+	"rootEntityVersionId"
+];
+/** Copy only the lineage fields that have values, so spans don't carry undefined keys */
+function ownEntityVersionId(span) {
+	return span instanceof BaseSpan ? span.ownEntityVersionId : void 0;
+}
+function definedLineage(source) {
+	const lineage = {};
+	for (const key of LINEAGE_KEYS) {
+		const value = source[key];
+		if (value !== void 0 && value !== null) lineage[key] = value;
+	}
+	return lineage;
+}
 /**
 * Determines if a span type should be considered internal based on flags.
 * Returns false if flags are undefined.
@@ -3290,6 +3315,17 @@ var BaseSpan = class BaseSpan {
 	isExcluded;
 	/** Cached canonical correlation context for this live span */
 	correlationContext;
+	/**
+	* Parent and root entity restored by `rebuildSpan()`. A rebuilt span has no
+	* live `parent`, so its original ancestors are only known from the cached export.
+	*/
+	restoredLineage;
+	/**
+	* Version declared for this span's own entity, or inherited from a parent span
+	* of the same entity. Unlike `metadata.entityVersionId`, never an ancestor's
+	* version for a different entity.
+	*/
+	ownEntityVersionId;
 	/** Child spans that have started but not yet ended */
 	#openChildren;
 	/** The span whose open-child set currently tracks this span: the parent, or a live ancestor after promotion */
@@ -3327,6 +3363,9 @@ var BaseSpan = class BaseSpan {
 		this.entityType = options.entityType ?? entityParent?.entityType;
 		this.entityId = options.entityId ?? entityParent?.entityId;
 		this.entityName = options.entityName ?? entityParent?.entityName;
+		const declaredVersion = options.metadata?.entityVersionId;
+		const sameEntityParent = entityParent instanceof BaseSpan && entityParent.entityType === this.entityType && entityParent.entityId === this.entityId;
+		this.ownEntityVersionId = typeof declaredVersion === "string" ? declaredVersion : sameEntityParent ? entityParent.ownEntityVersionId : void 0;
 		if (this.isExcluded) {
 			this.attributes = {};
 			return;
@@ -3475,18 +3514,62 @@ var BaseSpan = class BaseSpan {
 			current = current.parent;
 		}
 	}
-	/** Build and cache the canonical correlation context for this live span. */
+	/**
+	* Restore the parent and root entity a span had before it was exported and
+	* rebuilt (durable execution), so it and its new children keep their lineage.
+	*/
+	restoreEntityLineage(cached) {
+		this.ownEntityVersionId = cached.ownEntityVersionId ?? void 0;
+		const lineage = definedLineage(cached);
+		if (Object.keys(lineage).length > 0) {
+			this.restoredLineage = lineage;
+			this.correlationContext = void 0;
+		}
+	}
+	/**
+	* Build and cache the canonical correlation context for this live span.
+	*
+	* Parent entity: the nearest ancestor that is not internal or excluded, the
+	* same rule used for entity inheritance. Root entity: the top of the
+	* in-process parent chain, which is not necessarily the distributed trace's
+	* root when the trace continues from another service. The root walk does not
+	* skip internal spans, so the root can name an entity whose span is not
+	* exported. Logs, metrics, scores and feedback share these values.
+	*
+	* When the top of the live chain was rebuilt, its original ancestors only
+	* survive in the restored lineage, so it supplies the root and, when no live
+	* ancestor qualifies, the parent.
+	*/
 	getCorrelationContext() {
 		if (this.correlationContext) return this.correlationContext;
 		const metadata = this.metadata ?? {};
 		const getMetadataString = (key) => typeof metadata[key] === "string" ? metadata[key] : void 0;
-		const getSpanMetadataString = (span, key) => {
-			const m = span?.metadata;
-			return m && typeof m[key] === "string" ? m[key] : void 0;
-		};
 		const parentSpan = this.getParentSpan(false);
 		let rootSpan = this;
 		while (rootSpan.parent) rootSpan = rootSpan.parent;
+		const restored = rootSpan instanceof BaseSpan ? rootSpan.restoredLineage : void 0;
+		const parentLineage = parentSpan ? {
+			parentEntityType: parentSpan.entityType,
+			parentEntityId: parentSpan.entityId,
+			parentEntityName: parentSpan.entityName,
+			parentEntityVersionId: ownEntityVersionId(parentSpan)
+		} : {
+			parentEntityType: restored?.parentEntityType,
+			parentEntityId: restored?.parentEntityId,
+			parentEntityName: restored?.parentEntityName,
+			parentEntityVersionId: restored?.parentEntityVersionId
+		};
+		const rootLineage = restored ? {
+			rootEntityType: restored.rootEntityType,
+			rootEntityId: restored.rootEntityId,
+			rootEntityName: restored.rootEntityName,
+			rootEntityVersionId: restored.rootEntityVersionId
+		} : {
+			rootEntityType: rootSpan.entityType,
+			rootEntityId: rootSpan.entityId,
+			rootEntityName: rootSpan.entityName,
+			rootEntityVersionId: ownEntityVersionId(rootSpan)
+		};
 		const rootTags = rootSpan.tags?.length ? [...rootSpan.tags] : void 0;
 		this.correlationContext = {
 			traceId: this.traceId,
@@ -3496,14 +3579,8 @@ var BaseSpan = class BaseSpan {
 			entityId: this.entityId,
 			entityName: this.entityName,
 			entityVersionId: getMetadataString("entityVersionId"),
-			parentEntityType: parentSpan?.entityType,
-			parentEntityId: parentSpan?.entityId,
-			parentEntityName: parentSpan?.entityName,
-			parentEntityVersionId: getSpanMetadataString(parentSpan, "entityVersionId"),
-			rootEntityType: rootSpan.entityType,
-			rootEntityId: rootSpan.entityId,
-			rootEntityName: rootSpan.entityName,
-			rootEntityVersionId: getSpanMetadataString(rootSpan, "entityVersionId"),
+			...parentLineage,
+			...rootLineage,
 			userId: getMetadataString("userId"),
 			organizationId: getMetadataString("organizationId"),
 			resourceId: getMetadataString("resourceId"),
@@ -3524,6 +3601,7 @@ var BaseSpan = class BaseSpan {
 		const hideOutput = this.traceState?.hideOutput ?? false;
 		const nestedUnderParent = this.traceState?.nestedUnderParent ?? false;
 		const links = validLinks(this.links);
+		const correlation = this.getCorrelationContext();
 		return {
 			id: this.id,
 			traceId: this.traceId,
@@ -3543,6 +3621,7 @@ var BaseSpan = class BaseSpan {
 			isEvent: this.isEvent,
 			isRootSpan: this.isRootSpan,
 			...this.isInternal ? { isInternal: true } : {},
+			...definedLineage(correlation),
 			parentSpanId: this.getParentSpanId(includeInternalSpans),
 			externalParentSpanId: this.getExportedExternalParentSpanId(includeInternalSpans),
 			...nestedUnderParent ? { nestedUnderParent: true } : {},
@@ -3550,6 +3629,14 @@ var BaseSpan = class BaseSpan {
 			...this.isRootSpan && !nestedUnderParent && this.tags?.length ? { tags: this.tags } : {}
 		};
 	}
+	/** Returns the span saved for a later `rebuildSpan()`, with its trace state */
+	snapshot() {
+		return {
+			...this.exportSpan(),
+			ownEntityVersionId: this.ownEntityVersionId ?? null,
+			...this.traceState ? { traceState: this.traceState } : {}
+		};
+	}
 	get externalTraceId() {
 		return this.isValid ? this.traceId : void 0;
 	}
@@ -5156,7 +5243,7 @@ var BaseObservabilityInstance = class extends MastraBase {
 	* - Can have end(), update(), error() called on it
 	* - Will emit SPAN_ENDED or SPAN_UPDATED when those methods are called
 	*
-	* @param cached - The exported span data to rebuild from
+	* @param cached - The span snapshot to rebuild from
 	* @returns A span that can have lifecycle methods called on it
 	*/
 	rebuildSpan(cached) {
@@ -5176,15 +5263,27 @@ var BaseObservabilityInstance = class extends MastraBase {
 			entityId: cached.entityId,
 			entityName: cached.entityName,
 			tracingPolicy: cached.isInternal ? { internal: InternalSpans.ALL } : void 0,
-			traceState: cached.nestedUnderParent ? {
-				requestContextKeys: [],
-				nestedUnderParent: true
-			} : void 0
+			traceState: this.rebuildTraceState(cached)
 		});
+		if (span instanceof BaseSpan) span.restoreEntityLineage(cached);
 		this.wireSpanLifecycle(span);
 		return span;
 	}
 	/**
+	* Restore the trace-level rules for a rebuilt span. Spans saved with
+	* `exportSpan()` before `snapshot()` existed fall back to the instance's
+	* configured keys, so an in-flight durable run keeps at least those across an upgrade.
+	*/
+	rebuildTraceState(cached) {
+		if (cached.traceState) return cached.traceState;
+		const fallback = this.computeTraceState();
+		if (!cached.nestedUnderParent) return fallback;
+		return {
+			requestContextKeys: fallback?.requestContextKeys ?? [],
+			nestedUnderParent: true
+		};
+	}
+	/**
 	* Get current configuration
 	*/
 	getConfig() {