> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# 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](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/datadog) 較為簡單。它支援 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](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/datadog) 相同的資料結構與 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**:

```bash
npm install @mastra/datadog dd-trace
```

**pnpm**:

```bash
pnpm add @mastra/datadog dd-trace
```

**Yarn**:

```bash
yarn add @mastra/datadog dd-trace
```

**Bun**:

```bash
bun add @mastra/datadog dd-trace
```

Bridge 需要安裝 `dd-trace`，並使用本機 Datadog Agent（或相容的 OTLP receiver）接收 APM 資料。如需 Agent 設定詳情，請參閱 Exporter 頁面的 [APM 必要條件](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/datadog)。

## 設定

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

1. 初始化 `dd-trace`，讓其自動 instrumentation patch HTTP、資料庫與 framework library
2. 將 DatadogBridge 加入 Mastra Observability 設定

### 步驟 1：初始化 dd-trace

`dd-trace` 必須在任何其他 import 前初始化，其自動 instrumentation 才能在載入時 patch library。Bridge 會偵測已初始化的 tracer 並重複使用。

```typescript
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 設定：

```typescript
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',
    ],
  },
})
```

```bash
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。

```typescript
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](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/datadog)。

## Trace 階層

使用 DatadogBridge 後，Trace 會跨越 dd-trace 與 Mastra 邊界維持正確階層。Tool 與 Processor 所發出的服務呼叫會顯示在正確的 Mastra span 下：

```text
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 類型對應](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/datadog)。

## 使用 tag

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

```typescript
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 中篩選這些值：

```typescript
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 疑難排解](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/datadog)章節。

## 相關內容

- [Tracing 總覽](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)
- [Datadog Exporter](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/datadog)－僅限 LLM Observability，不含 `dd-trace` APM
- [DatadogBridge 參考](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/bridges/datadog)－API 文件
- [Datadog APM 文件](https://docs.datadoghq.com/tracing/)
- [Datadog LLM Observability 文件](https://docs.datadoghq.com/llm_observability/)