@mastra/observability 1.16.6 → 1.17.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @mastra/observability
 
+## 1.17.0-alpha.0
+
+### Minor Changes
+
+- Fixed traces that start under an external parent span not appearing in Mastra Studio. ([#20499](https://github.com/mastra-ai/mastra/pull/20499))
+
+### Patch Changes
+
+- Updated dependencies [[`088e41e`](https://github.com/mastra-ai/mastra/commit/088e41e434ed05f2c674b254f1034ec46a57a7be), [`b2f0013`](https://github.com/mastra-ai/mastra/commit/b2f0013375588d40c03c13e843b99c0ff8872ca5), [`3b541ae`](https://github.com/mastra-ai/mastra/commit/3b541ae5d410c52b80a7e381d84d021cddb9a449), [`ae79e34`](https://github.com/mastra-ai/mastra/commit/ae79e34c0bd8674fc24c7524217bfc4a051c6136), [`a6c4399`](https://github.com/mastra-ai/mastra/commit/a6c4399763590b3dae21a2c81826e89a3b1deee4)]:
+  - @mastra/core@1.59.0-alpha.0
+
 ## 1.16.6
 
 ### Patch Changes

package/dist/index.cjs

@@ -2541,8 +2541,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;
 	/**
@@ -2649,6 +2651,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;
@@ -2723,6 +2736,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 } : {}
 		};
 	}
@@ -2765,6 +2779,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();
@@ -2773,7 +2788,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;
 			}
 		}
@@ -2787,6 +2803,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;
@@ -3035,11 +3053,13 @@ var BaseObservabilityInstance = class extends _mastra_core_base.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,