Datadog Bridge

警告

Datadog Bridge 目前為實驗性功能。API 與設定選項可能在未來版本中變更。

Datadog Bridge 能在 Mastra Tracing 系統與 Datadog 之間進行雙向整合。Exporter 會在執行完成後傳送 Trace 資料，而 Bridge 則會即時建立原生 dd-trace span，讓 Tool 與 Processor 內自動 instrumentation 的 APM 作業（HTTP 呼叫、資料庫查詢等）正確巢狀置於其父 Mastra span 下。

沒有使用 dd-trace APM？

如果只需要傳送 LLM Observability 資料，且未使用 dd-trace APM 自動 instrumentation，則使用 Datadog Exporter 較為簡單。它支援 agentless 模式，無須本機 Agent 即可將 span 直接傳送至 Datadog。

使用 Bridge 的時機

下列情況適合使用 DatadogBridge：

• 應用程式使用 dd-trace 自動 instrumentation（HTTP Server、資料庫 Client 等）
• 希望 Tool、MCP Tool 或輸出 Processor 所發出的 APM 服務呼叫顯示在其父 Mastra span 下，而不是 request handler 下
• 需要 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
• 啟用中 scope 內自動 instrumentation 的作業會連結至正確的父 Mastra span
• 沒有明確的 Mastra 父 span 時，繼承啟用中的 dd-trace context（例如傳入 request span）

LLM Observability 發送（span 結束時）：

• 透過 dd-trace 的 LLM Observability pipeline 發送 annotation（模型資訊、token 用量、輸入／輸出、錯誤）
• 使用巢狀 llmobs.trace() 呼叫，在 Datadog LLM Observability 中維持父子關係
• 重複使用與 Datadog Exporter 相同的資料結構與 span-kind 對應

Trace 與 Log 關聯

如果沒有 Bridge，Datadog Exporter 只會在 Trace 完成後建立 LLM Observability span。執行期間，scope 中沒有啟用的 dd-trace span，因此 Tool 所發出的 HTTP 或資料庫呼叫會改用當時啟用的 dd-trace span，通常是傳入的 request handler。結果是 MCP Tool 或輸出 Processor 發出的服務呼叫會顯示為 request span 的子項，而不是實際發出呼叫的 Agent 或 Processor span 子項。

Bridge 會事先建立真正的 dd-trace span，確保自動 instrumentation 執行時使用正確的 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，讓其自動 instrumentation patch HTTP、資料庫與 framework library
2. 將 DatadogBridge 加入 Mastra Observability 設定

步驟 1：初始化 dd-trace

dd-trace 必須在任何其他 import 前初始化，其自動 instrumentation 才能在載入時 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 匯入及初始化 dd-trace。

步驟 2：設定 Mastra

將 DatadogBridge 加入 Mastra Observability 設定：

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 資料。由於 APM 資料一律透過 Agent 路由，因此這是使用 dd-trace 自動 instrumentation 時的典型設定。

如果沒有本機 Datadog Agent，且只需要 LLM Observability 資料（不需要 APM 自動 instrumentation），可以啟用 agentless 模式，將資料直接傳送至 Datadog。在此情況下，必須提供 API Key。

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 類型對應

Bridge 對 LLM Observability 使用與 Datadog Exporter 相同的 span-kind 對應。請參閱 Exporter 頁面的 span 類型對應。

使用 tag

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

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

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

將 context key 提升為扁平 tag

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

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 連線
• 確認 Observability 設定中的 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 文件