@mastra/datadog 1.4.15 → 1.4.16-alpha.1

package/dist/bridge.d.ts

@@ -70,6 +70,15 @@ export interface DatadogBridgeConfig extends BaseExporterConfig {
      * LLM Observability tags instead of being nested in annotations.metadata.
      */
     requestContextKeys?: string[];
+    /**
+     * How long `flush()` waits, in milliseconds, after handing data to dd-trace.
+     * dd-trace sends LLM Observability spans and evaluations from a background
+     * writer and offers no way to await that request, so the wait keeps a process
+     * that exits right after `flush()` from cutting the send off. The wait only
+     * happens when something was sent since the last flush. Set to 0 to disable.
+     * Defaults to 2000.
+     */
+    flushGraceMs?: number;
 }
 /**
  * Datadog Bridge for Mastra Observability.
@@ -82,8 +91,15 @@ export declare class DatadogBridge extends BaseExporter implements Observability
     name: string;
     private config;
     private ddSpanMap;
+    /** Keys of the links each dd span was started with, so links set later are added once at finish. */
+    private startLinkKeys;
     private traceContext;
     private openSpanCounts;
+    private flushGraceMs;
+    /** True when spans or evaluations were handed to dd-trace since the last flush() */
+    private pendingSend;
+    /** Grace wait in progress, shared by flush() calls that overlap it */
+    private graceWait;
     constructor(config?: DatadogBridgeConfig);
     /**
      * Create a dd-trace span eagerly when a Mastra span is constructed.
@@ -124,6 +140,14 @@ export declare class DatadogBridge extends BaseExporter implements Observability
     private buildAnnotations;
     private setErrorTags;
     flush(): Promise<void>;
+    /**
+     * `llmobs.flush()` returns before the background writer's HTTP request
+     * completes and dd-trace gives nothing to await, so wait a bounded time
+     * instead. Starts one wait per batch of new data, so the repeated flushes
+     * during shutdown don't stack. A flush that overlaps a running wait joins
+     * it, so no caller resolves before the data it produced had its wait.
+     */
+    private waitForBackgroundSend;
     shutdown(): Promise<void>;
 }
 //# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,YAAY,EAKZ,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACV,QAAQ,EACR,OAAO,EACR,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,YAAY,EAAuB,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AA+DhE;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,qBAAa,aAAc,SAAQ,YAAa,YAAW,mBAAmB;IAC5E,IAAI,SAAoB;IAExB,OAAO,CAAC,MAAM,CAA8E;IAC5F,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,cAAc,CAA6B;IAEnD,YAAY,MAAM,GAAE,mBAAwB,EA8C3C;IAED;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAAG,OAAO,GAAG,SAAS,CAyEpE;IAED;;OAEG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEpE;IAED;;OAEG;IACH,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD;IAEK,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCnD;IAED,OAAO,CAAC,sBAAsB;IAmB9B;;OAEG;IACH,UAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BtE;IAED,OAAO,CAAC,kBAAkB;IA0C1B,OAAO,CAAC,eAAe;IASvB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAwD7B;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAIjD;IAED,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,gBAAgB;IAiGxB,OAAO,CAAC,YAAY;IASd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3B;IAEK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B9B;CACF"}
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,YAAY,EAKZ,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACV,QAAQ,EACR,OAAO,EACR,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,YAAY,EAAuB,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AA+DhE;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,qBAAa,aAAc,SAAQ,YAAa,YAAW,mBAAmB;IAC5E,IAAI,SAAoB;IAExB,OAAO,CAAC,MAAM,CAA8E;IAC5F,OAAO,CAAC,SAAS,CAA0B;IAC3C,oGAAoG;IACpG,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,YAAY,CAAS;IAC7B,oFAAoF;IACpF,OAAO,CAAC,WAAW,CAAS;IAC5B,sEAAsE;IACtE,OAAO,CAAC,SAAS,CAA8B;IAE/C,YAAY,MAAM,GAAE,mBAAwB,EA+C3C;IAED;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAAG,OAAO,GAAG,SAAS,CA8EpE;IAED;;OAEG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEpE;IAED;;OAEG;IACH,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD;IAEK,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCnD;IAED,OAAO,CAAC,sBAAsB;IAmB9B;;OAEG;IACH,UAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BtE;IAED,OAAO,CAAC,kBAAkB;IA0C1B,OAAO,CAAC,eAAe;IASvB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAqE7B;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAIjD;IAED,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,gBAAgB;IAiGxB,OAAO,CAAC,YAAY;IASd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAoB3B;IAED;;;;;;OAMG;YACW,qBAAqB;IAY7B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CA2B9B;CACF"}

package/dist/index.cjs

@@ -83,6 +83,20 @@ function formatUsageMetrics(usage) {
 * Utility functions for Datadog LLM Observability Exporter
 */
 /**
+* Datadog span links for Mastra span links, such as the caller of a served MCP
+* request. Each link is resolved from a W3C `traceparent`, so only full-length
+* W3C IDs are kept, and links dd-trace can't resolve are skipped.
+*/
+function toDatadogLinks(links) {
+	const ddLinks = [];
+	for (const link of links ?? []) {
+		if (!/^[0-9a-f]{32}$/.test(link.traceId) || !/^[0-9a-f]{16}$/.test(link.spanId)) continue;
+		const context = dd_trace.default.extract("text_map", { traceparent: `00-${link.traceId}-${link.spanId}-01` });
+		if (context) ddLinks.push({ context });
+	}
+	return ddLinks;
+}
+/**
 * Maps Mastra SpanTypes to Datadog LLMObs span kinds for the legacy hierarchy
 * (no `model-inference-span` feature). MODEL_STEP is the actual API call here
 * because MODEL_INFERENCE doesn't exist.
@@ -333,10 +347,18 @@ var DatadogBridge = class extends _mastra_observability.BaseExporter {
 	name = "datadog-bridge";
 	config;
 	ddSpanMap = /* @__PURE__ */ new Map();
+	/** Keys of the links each dd span was started with, so links set later are added once at finish. */
+	startLinkKeys = /* @__PURE__ */ new WeakMap();
 	traceContext = /* @__PURE__ */ new Map();
 	openSpanCounts = /* @__PURE__ */ new Map();
+	flushGraceMs;
+	/** True when spans or evaluations were handed to dd-trace since the last flush() */
+	pendingSend = false;
+	/** Grace wait in progress, shared by flush() calls that overlap it */
+	graceWait = null;
 	constructor(config = {}) {
 		super(config);
+		this.flushGraceMs = config.flushGraceMs ?? 2e3;
 		const mlApp = config.mlApp ?? process.env.DD_LLMOBS_ML_APP;
 		const apiKey = config.apiKey ?? process.env.DD_API_KEY;
 		const site = config.site ?? process.env.DD_SITE ?? "datadoghq.com";
@@ -396,10 +418,13 @@ var DatadogBridge = class extends _mastra_observability.BaseExporter {
 				if (apmParentDdSpan) parentSource = "active-scope";
 			}
 			if (!llmobsParentDdSpan && externalParentId) llmobsParentDdSpan = apmParentDdSpan;
+			const links = toDatadogLinks(options.links);
 			const ddSpan = dd_trace.default.startSpan(options.name, {
 				...apmParentDdSpan ? { childOf: apmParentDdSpan } : {},
-				...options.startTime ? { startTime: toDate(options.startTime).getTime() } : {}
+				...options.startTime ? { startTime: toDate(options.startTime).getTime() } : {},
+				...links.length > 0 ? { links } : {}
 			});
+			if (options.links?.length) this.startLinkKeys.set(ddSpan, new Set(options.links.map((link) => `${link.traceId}:${link.spanId}`)));
 			const ddContext = ddSpan.context?.();
 			const spanId = ddContext?.toSpanId?.(true) ?? generateSpanId();
 			const traceId = ddContext?.toTraceId?.(true) ?? (externalParentId ? options.parent?.traceId ?? generateTraceId() : generateTraceId());
@@ -440,6 +465,7 @@ var DatadogBridge = class extends _mastra_observability.BaseExporter {
 			return;
 		}
 		try {
+			this.pendingSend = true;
 			dd_trace.default.llmobs.submitEvaluation({
 				traceId: score.traceId,
 				spanId: toDatadogSpanId(score.spanId)
@@ -562,7 +588,20 @@ var DatadogBridge = class extends _mastra_observability.BaseExporter {
 			});
 		}
 		try {
-			if (typeof ddSpan.finish === "function") ddSpan.finish(endTime.getTime());
+			const startKeys = this.startLinkKeys.get(ddSpan);
+			const lateLinks = toDatadogLinks(span.links?.filter((link) => !startKeys?.has(`${link.traceId}:${link.spanId}`)));
+			if (lateLinks.length > 0 && typeof ddSpan.addLinks === "function") ddSpan.addLinks(lateLinks);
+		} catch (error) {
+			this.logger.error("[DatadogBridge] Failed to add span links", {
+				error,
+				spanId: span.id
+			});
+		}
+		try {
+			if (typeof ddSpan.finish === "function") {
+				this.pendingSend = true;
+				ddSpan.finish(endTime.getTime());
+			}
 		} catch (error) {
 			this.logger.error("[DatadogBridge] Failed to finish dd span", {
 				error,
@@ -667,6 +706,7 @@ var DatadogBridge = class extends _mastra_observability.BaseExporter {
 		} catch (e) {
 			this.logger.error("Error flushing llmobs", { error: e });
 		}
+		await this.waitForBackgroundSend();
 		try {
 			await flushApmExporter();
 			this.logger.debug("Datadog APM exporter flushed");
@@ -674,11 +714,32 @@ var DatadogBridge = class extends _mastra_observability.BaseExporter {
 			this.logger.error("Error flushing Datadog APM exporter", { error: e });
 		}
 	}
+	/**
+	* `llmobs.flush()` returns before the background writer's HTTP request
+	* completes and dd-trace gives nothing to await, so wait a bounded time
+	* instead. Starts one wait per batch of new data, so the repeated flushes
+	* during shutdown don't stack. A flush that overlaps a running wait joins
+	* it, so no caller resolves before the data it produced had its wait.
+	*/
+	async waitForBackgroundSend() {
+		if (!(this.flushGraceMs > 0) || !Number.isFinite(this.flushGraceMs)) return;
+		if (this.pendingSend) {
+			this.pendingSend = false;
+			const wait = new Promise((resolve) => setTimeout(resolve, this.flushGraceMs)).finally(() => {
+				if (this.graceWait === wait) this.graceWait = null;
+			});
+			this.graceWait = wait;
+		}
+		await this.graceWait;
+	}
 	async shutdown() {
 		for (const [spanId, ddSpan] of this.ddSpanMap) {
 			this.logger.warn(`[DatadogBridge] Force-finishing APM span that was not properly closed [id=${spanId}]`);
 			try {
-				if (typeof ddSpan.finish === "function") ddSpan.finish();
+				if (typeof ddSpan.finish === "function") {
+					this.pendingSend = true;
+					ddSpan.finish();
+				}
 			} catch {}
 		}
 		this.ddSpanMap.clear();
@@ -743,8 +804,14 @@ var DatadogExporter = class extends _mastra_observability.BaseExporter {
 	config;
 	traceContext = /* @__PURE__ */ new Map();
 	traceState = /* @__PURE__ */ new Map();
+	flushGraceMs;
+	/** True when spans or evaluations were handed to dd-trace since the last flush() */
+	pendingSend = false;
+	/** Grace wait in progress, shared by flush() calls that overlap it */
+	graceWait = null;
 	constructor(config = {}) {
 		super(config);
+		this.flushGraceMs = config.flushGraceMs ?? 2e3;
 		const mlApp = config.mlApp ?? process.env.DD_LLMOBS_ML_APP;
 		const apiKey = config.apiKey ?? process.env.DD_API_KEY;
 		const site = config.site ?? process.env.DD_SITE ?? "datadoghq.com";
@@ -922,6 +989,7 @@ var DatadogExporter = class extends _mastra_observability.BaseExporter {
 			return;
 		}
 		try {
+			this.pendingSend = true;
 			dd_trace.default.llmobs.submitEvaluation({
 				traceId: exported.traceId,
 				spanId: exported.spanId
@@ -956,6 +1024,25 @@ var DatadogExporter = class extends _mastra_observability.BaseExporter {
 		} catch (e) {
 			this.logger.error("Error flushing llmobs", { error: e });
 		}
+		await this.waitForBackgroundSend();
+	}
+	/**
+	* `llmobs.flush()` returns before the background writer's HTTP request
+	* completes and dd-trace gives nothing to await, so wait a bounded time
+	* instead. Starts one wait per batch of new data, so the repeated flushes
+	* during shutdown don't stack. A flush that overlaps a running wait joins
+	* it, so no caller resolves before the data it produced had its wait.
+	*/
+	async waitForBackgroundSend() {
+		if (!(this.flushGraceMs > 0) || !Number.isFinite(this.flushGraceMs)) return;
+		if (this.pendingSend) {
+			this.pendingSend = false;
+			const wait = new Promise((resolve) => setTimeout(resolve, this.flushGraceMs)).finally(() => {
+				if (this.graceWait === wait) this.graceWait = null;
+			});
+			this.graceWait = wait;
+		}
+		await this.graceWait;
 	}
 	/**
 	* Gracefully shuts down the exporter.
@@ -1132,6 +1219,7 @@ var DatadogExporter = class extends _mastra_observability.BaseExporter {
 			provider: ownAttrs?.provider ?? inheritedModelAttrs?.provider
 		};
 		const startTime = toDate(span.startTime);
+		const links = toDatadogLinks(span.links);
 		const endTime = span.endTime ? toDate(span.endTime) : span.isEvent ? startTime : /* @__PURE__ */ new Date();
 		return {
 			traceOptions: {
@@ -1141,7 +1229,8 @@ var DatadogExporter = class extends _mastra_observability.BaseExporter {
 				userId: traceCtx.userId,
 				startTime,
 				...kind === "llm" && attrs?.model ? { modelName: attrs.model } : {},
-				...kind === "llm" && attrs?.provider ? { modelProvider: attrs.provider } : {}
+				...kind === "llm" && attrs?.provider ? { modelProvider: attrs.provider } : {},
+				...links.length > 0 ? { links } : {}
 			},
 			endTimeMs: endTime.getTime()
 		};
@@ -1158,6 +1247,7 @@ var DatadogExporter = class extends _mastra_observability.BaseExporter {
 			model: span.attributes?.model,
 			provider: span.attributes?.provider
 		} : inheritedModelAttrs;
+		this.pendingSend = true;
 		dd_trace.default.llmobs.trace(traceOptions, (ddSpan) => {
 			const annotations = this.buildAnnotations(span);
 			if (Object.keys(annotations).length > 0) dd_trace.default.llmobs.annotate(ddSpan, annotations);