Datadog bridge

注意

Datadog Bridge 目前仍屬實驗性質。API 和配置選項可能會在未來版本中變更。

Datadog Bridge 可在 Mastra tracing 系統與 Datadog 之間進行雙向整合。Exporter 會在執行完成後才傳送 trace 數據，而 bridge 則會即時建立原生 dd-trace span，讓 Tool 和 processor 內經自動檢測的 APM 操作（HTTP 呼叫、數據庫查詢等），正確地嵌套於其父 Mastra span 之下。

沒有使用 dd-trace APM？

如果你只需傳送 LLM Observability 數據，而且不使用 dd-trace APM 自動檢測，Datadog Exporter 會更簡單。它支援 agentless 模式，無需本機 agent 即可將 span 直接傳送至 Datadog。

何時使用 bridge

在以下情況使用 DatadogBridge：

• 在應用程式中使用 dd-trace 自動檢測（HTTP 伺服器、數據庫客戶端等）
• 希望 Tool、MCP Tool 或輸出 processor 發出的 APM 服務呼叫，顯示在其父 Mastra span 之下，而非請求處理常式之下
• 需要 APM trace 和 LLM Observability 數據共用一致的 trace 拓撲
• 正在建立分佈式系統，而 Datadog trace context 必須跨服務傳播

運作方式

DatadogBridge 會參與 dd-trace pipeline 的兩個部分：

APM context 傳播（即時）：

• 建立每個 Mastra span 時，透過 tracer.startSpan() 建立 dd-trace APM span
• 執行期間，透過 tracer.scope().activate() 在 dd-trace 的 scope 中啟用 APM span
• active scope 內經自動檢測的操作，會以正確的 Mastra span 作為父 span
• 沒有明確的 Mastra 父 span 時，繼承 active dd-trace context（例如傳入請求的 span）

發出 LLM Observability 數據（span 結束時）：

• 透過 dd-trace 的 LLM Observability pipeline 發出 annotation（模型資料、token 使用量、輸入／輸出、錯誤）
• 使用嵌套的 llmobs.trace() 呼叫，在 Datadog LLM Observability 中維持父子關係
• 重用與 Datadog Exporter 相同的數據結構及 span kind 映射

Trace 與日誌關聯

若沒有 bridge，Datadog Exporter 只會在 trace 完成後建立 LLM Observability span。執行期間，scope 中沒有 active dd-trace span，因此 Tool 發出的任何 HTTP 或數據庫呼叫，都會改為歸入當時 active 的 dd-trace span，通常是傳入請求的處理常式。結果是 MCP Tool 或輸出 processor 發出的服務呼叫，會顯示為請求 span 的子 span，而非實際發出呼叫的 Agent 或 processor span 的子 span。

Bridge 會預先建立真正的 dd-trace span，以解決此問題，讓自動檢測執行時使用正確的 scope。

安裝

npm

npm install @mastra/datadog dd-trace

pnpm

pnpm add @mastra/datadog dd-trace

Yarn

yarn add @mastra/datadog dd-trace

Bun

bun add @mastra/datadog dd-trace

Bridge 要求安裝 dd-trace，並需要本機 Datadog Agent（或兼容的 OTLP receiver）接收 APM 數據。有關 agent 設定的詳情，請參閱 exporter 頁面的 APM 先決條件。

配置

使用 DatadogBridge 需要完成兩個步驟：

1. 初始化 dd-trace，讓其自動檢測功能 patch HTTP、數據庫及 framework library
2. 將 DatadogBridge 加入 Mastra 可觀測性配置

步驟 1：初始化 dd-trace

dd-trace 必須在任何其他 import 之前初始化，讓其自動檢測功能可在載入時 patch library。Bridge 會偵測已初始化的 tracer 並重用。

src/mastra/index.ts

import tracer from 'dd-trace'

tracer.init({
  service: process.env.DD_SERVICE || 'my-mastra-app',
  env: process.env.DD_ENV || 'production',
  version: process.env.DD_VERSION,
})

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { DatadogBridge } from '@mastra/datadog'

// ...

備註

請在應用程式進入點檔案的最頂部、任何其他 import 之前 import 並初始化 dd-trace。

步驟 2：Mastra 配置

將 DatadogBridge 加入 Mastra 可觀測性配置：

src/mastra/index.ts

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
      },
    },
  }),
  bundler: {
    externals: [
      'dd-trace',
      '@datadog/native-metrics',
      '@datadog/native-appsec',
      '@datadog/native-iast-taint-tracking',
      '@datadog/pprof',
    ],
  },
})

.env

DD_SERVICE=my-mastra-app
DD_ENV=production
DD_VERSION=1.0.0
DD_LLMOBS_ML_APP=my-llm-app

初始化 dd-trace 後，它會將 APM 數據路由至 localhost:8126 上的本機 Datadog Agent。Bridge 會在同一 tracer 上啟用 LLM Observability，因此兩組數據都會顯示在 Datadog 的同一服務下。

使用 bridge 時不需要任何 Mastra exporter，APM 和 LLM Observability 數據都會流經 dd-trace。如果想將 trace 傳送至其他目的地，仍可加入 Mastra exporter。

Agent 模式與 agentless 模式

Bridge 預設使用 agent 模式（agentless: false）。此模式假設本機 Datadog Agent 正在 localhost:8126 執行，以接收 APM 和 LLM Observability 數據。使用 dd-trace 自動檢測時通常會採用此設定，因為 APM 數據一律透過 agent 路由。

如果沒有本機 Datadog Agent，而且只需要 LLM Observability 數據（不使用 APM 自動檢測），可啟用 agentless 模式，將數據直接傳送至 Datadog。在此情況下，必須提供 API 金鑰。

new DatadogBridge({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  apiKey: process.env.DD_API_KEY!,
  agentless: true,
})

備註

對大多數 bridge 使用者而言，agent 模式是合適的選擇。APM 數據無法在 agentless 模式下傳送，因此啟用 agentless 會將 LLM Observability 流量與 APM 流量分開。如果只需要 LLM Observability 而不使用 agent，請改用 Datadog Exporter。

Trace 階層

使用 DatadogBridge 時，你的 trace 可跨越 dd-trace 與 Mastra 邊界維持正確的階層。Tool 和 processor 發出的服務呼叫會顯示在正確的 Mastra span 之下：

HTTP POST /api/chat (from web framework instrumentation)
└── agent.orchestrator (from Mastra via DatadogBridge)
    ├── chat gpt-5.4 (LLM call)
    ├── tool.execute search (tool execution)
    │   └── HTTP GET api.example.com (auto-instrumented from inside the tool)
    └── processor.guardrail (output processor)
        └── HTTP POST guardrail-service/check (auto-instrumented from inside the processor)

在 Datadog 中，APM trace 會顯示這個完整拓撲，而 LLM Observability 產品則會顯示 Agent 及 LLM 專用 span，包括其輸入、輸出及 token 指標。

Span type 映射

Bridge 對 LLM Observability 使用與 Datadog Exporter 相同的 span kind 映射。請參閱 exporter 頁面的 span type 映射。

使用 tag

Tag 可協助你在 Datadog 中分類及篩選 trace。執行 Agent 或 Workflow 時加入 tag：

const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'experiment-v2', 'user-request'],
  },
})

格式為 key:value 的 tag（例如 instance_name:career-scout-api）會拆分為結構化 tag 項目。不含冒號的 tag 會設為 true 值。

將 context key 提升為扁平 tag

使用 requestContextKeys，將 request context 或 span attribute 中的特定 key 提升為扁平、可建立索引的 LLM Observability tag，讓你可在 Datadog UI 中篩選這些 tag：

new DatadogBridge({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  requestContextKeys: ['tenantId', 'agentId'],
})

已提升的 key 會從 annotations.metadata 移除，並以扁平 tag 的形式加入每個 LLM Observability span。

疑難排解

如果 APM span 未有按預期連接至 Mastra span：

• 確認 dd-trace 在任何其他 import 之前初始化（它會在載入時 patch library）
• 確認本機 Datadog Agent 正在執行，並可透過 localhost:8126 連線
• 確保在可觀測性配置中將 DatadogBridge 設為 bridge（而非 exporters 中的項目）
• 確認沒有同時將 DatadogExporter 加入 exporters：同時使用兩者會重複發出 LLM Observability 數據

有關 dd-trace 與 bundler external 的原生模組兼容性問題，請參閱 Datadog exporter 疑難排解章節。

相關內容

• Tracing 概覽
• Datadog Exporter - 僅限 LLM Observability，不包括 dd-trace APM
• DatadogBridge 參考資料 - API 文件
• Datadog APM 文件
• Datadog LLM Observability 文件