@mastra/datadog 1.0.22 → 1.1.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @mastra/datadog
 
+## 1.1.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`c05c9a1`](https://github.com/mastra-ai/mastra/commit/c05c9a13230988cef6d438a62f37760f31927bc7), [`e24aacb`](https://github.com/mastra-ai/mastra/commit/e24aacba07bd66f5d95b636dc24016fca26b52cf), [`c721164`](https://github.com/mastra-ai/mastra/commit/c7211643f7ac861f83b19a3757cc921487fc9d75), [`1b55954`](https://github.com/mastra-ai/mastra/commit/1b559541c1e08a10e49d01ffc51a634dfc37a286), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`70017d7`](https://github.com/mastra-ai/mastra/commit/70017d72ab741b5d7040e2a15c251a317782e39e), [`e4942bc`](https://github.com/mastra-ai/mastra/commit/e4942bc7fdc903572f7d84f26d5e15f9d39c763d), [`39a3768`](https://github.com/mastra-ai/mastra/commit/39a3768a980c31ee689c675aa0015609f76191c4)]:
+  - @mastra/core@1.32.0-alpha.1
+  - @mastra/observability@1.11.1-alpha.1
+
+## 1.1.0-alpha.0
+
+### Minor Changes
+
+- Added a new `DatadogBridge` integration for Mastra tracing so Datadog can keep auto-instrumented HTTP, database, and framework spans nested under the agent, workflow, model, and tool spans that triggered them. ([#15716](https://github.com/mastra-ai/mastra/pull/15716))
+
+  ```typescript
+  import tracer from 'dd-trace';
+
+  tracer.init({
+    service: process.env.DD_SERVICE || 'my-mastra-app',
+    env: process.env.DD_ENV || 'production',
+  });
+
+  import { Mastra } from '@mastra/core';
+  import { Observability } from '@mastra/observability';
+  import { DatadogBridge } from '@mastra/datadog';
+
+  const mastra = new Mastra({
+    observability: new Observability({
+      configs: {
+        default: {
+          serviceName: 'my-mastra-app',
+          bridge: new DatadogBridge({
+            mlApp: process.env.DD_LLMOBS_ML_APP!,
+          }),
+        },
+      },
+    }),
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`6dcd65f`](https://github.com/mastra-ai/mastra/commit/6dcd65f2a34069e6dc43ba35f1d11119b9b40bef), [`1c2dda8`](https://github.com/mastra-ai/mastra/commit/1c2dda805fbfccc0abf55d4cb20cc34402dc3f0c), [`568777e`](https://github.com/mastra-ai/mastra/commit/568777ea8af77a672270b448dfd3996f9e75a964)]:
+  - @mastra/core@1.31.1-alpha.0
+  - @mastra/observability@1.11.1-alpha.0
+
 ## 1.0.22
 
 ### Patch Changes

package/dist/bridge.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Datadog Bridge for Mastra Observability
+ *
+ * This bridge enables bidirectional integration with dd-trace:
+ * 1. Creates real dd-trace APM spans eagerly when Mastra spans are created
+ * 2. Activates spans in dd-trace's scope so auto-instrumented operations
+ *    (HTTP requests, database queries, etc.) have correct parent spans
+ * 3. Registers those same spans with Datadog LLMObs and annotates them
+ *    before finish, avoiding a second synthetic APM span tree
+ *
+ * This fixes the core problem with the DatadogExporter: because the exporter
+ * creates LLMObs spans retroactively (after execution completes), there is no
+ * active dd-trace span in scope when tools and processors make outbound calls.
+ * dd-trace's auto-instrumentation can't find the correct parent, so APM spans
+ * fall back to the nearest active span (typically the request handler).
+ */
+import type { TracingEvent, ObservabilityBridge, CreateSpanOptions, SpanType, SpanIds } from '@mastra/core/observability';
+import { BaseExporter } from '@mastra/observability';
+import type { BaseExporterConfig } from '@mastra/observability';
+/**
+ * Configuration options for the Datadog Bridge.
+ */
+export interface DatadogBridgeConfig extends BaseExporterConfig {
+    /**
+     * Datadog API key. Required in agentless mode.
+     * Falls back to DD_API_KEY environment variable.
+     */
+    apiKey?: string;
+    /**
+     * ML application name for grouping traces.
+     * Required - falls back to DD_LLMOBS_ML_APP environment variable.
+     */
+    mlApp?: string;
+    /**
+     * Datadog site (e.g., 'datadoghq.com', 'datadoghq.eu').
+     * Falls back to DD_SITE environment variable, defaults to 'datadoghq.com'.
+     */
+    site?: string;
+    /**
+     * Service name for the application.
+     * Falls back to mlApp if not specified.
+     */
+    service?: string;
+    /**
+     * Environment name (e.g., 'production', 'staging').
+     * Falls back to DD_ENV environment variable.
+     */
+    env?: string;
+    /**
+     * Use agentless mode (direct HTTPS intake without a local Datadog Agent).
+     *
+     * Defaults to `false` for the bridge — most users running dd-trace
+     * auto-instrumentation already have a local Datadog Agent (required for
+     * APM data). Agentless mode only routes LLMObs data directly to Datadog
+     * intake, which would split your APM and LLMObs telemetry across two
+     * paths.
+     *
+     * Set to `true` if you only want LLMObs data (no APM auto-instrumentation)
+     * and don't have a local Datadog Agent. Falls back to the
+     * `DD_LLMOBS_AGENTLESS_ENABLED` environment variable.
+     */
+    agentless?: boolean;
+    /**
+     * Enable dd-trace automatic integrations (HTTP, database, etc.).
+     * Defaults to true since the bridge is designed for APM integration.
+     */
+    integrationsEnabled?: boolean;
+    /**
+     * Keys from the request context that should be promoted to flat Datadog
+     * LLM Observability tags instead of being nested in annotations.metadata.
+     */
+    requestContextKeys?: string[];
+}
+/**
+ * Datadog Bridge for Mastra Observability.
+ *
+ * Creates native dd-trace spans in real time during execution for proper APM
+ * context propagation, and uses the same live dd span for Datadog LLMObs
+ * tagging and annotations.
+ */
+export declare class DatadogBridge extends BaseExporter implements ObservabilityBridge {
+    name: string;
+    private config;
+    private ddSpanMap;
+    private traceContext;
+    private openSpanCounts;
+    constructor(config?: DatadogBridgeConfig);
+    /**
+     * Create a dd-trace span eagerly when a Mastra span is constructed.
+     */
+    createSpan(options: CreateSpanOptions<SpanType>): SpanIds | undefined;
+    /**
+     * Execute an async function within the dd-trace context of a Mastra span.
+     */
+    executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute a synchronous function within the dd-trace context of a Mastra span.
+     */
+    executeInContextSync<T>(spanId: string, fn: () => T): T;
+    private executeWithSpanContext;
+    /**
+     * Handle tracing events from the observability bus.
+     */
+    protected _exportTracingEvent(event: TracingEvent): Promise<void>;
+    private registerLlmObsSpan;
+    private getLlmObsTagger;
+    /**
+     * Annotate the eagerly-created dd span and finish it using the final Mastra
+     * span state.
+     */
+    private annotateAndFinishSpan;
+    private captureTraceContext;
+    private resolveTraceContext;
+    private releaseTraceContext;
+    private buildAnnotations;
+    private setErrorTags;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,YAAY,EAIZ,mBAAmB,EACnB,iBAAiB,EACjB,QAAQ,EACR,OAAO,EACR,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,YAAY,EAAuB,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AA8DhE;;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;gBAEvC,MAAM,GAAE,mBAAwB;IAyC5C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAAG,OAAO,GAAG,SAAS;IAgErE;;OAEG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrE;;OAEG;IACH,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIvD,OAAO,CAAC,sBAAsB;IAmB9B;;OAEG;cACa,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BvE,OAAO,CAAC,kBAAkB;IA0C1B,OAAO,CAAC,eAAe;IASvB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAwD7B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,gBAAgB;IA2FxB,OAAO,CAAC,YAAY;IASd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA2BhC"}