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

# 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](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/datadog) 會更簡單。它支援 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](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/datadog) 相同的數據結構及 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**:

```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-HK/docs/observability/integrations/exporters/datadog)。

## 配置

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

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

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

`dd-trace` 必須在任何其他 import 之前初始化，讓其自動檢測功能可在載入時 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 之前 import 並初始化 `dd-trace`。

### 步驟 2：Mastra 配置

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

```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 數據。使用 `dd-trace` 自動檢測時通常會採用此設定，因為 APM 數據一律透過 agent 路由。

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

```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-HK/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 type 映射

Bridge 對 LLM Observability 使用與 Datadog Exporter 相同的 span kind 映射。請參閱 exporter 頁面的 [span type 映射](https://mastra.zisheng.pro/zh-HK/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` 的 tag（例如 `instance_name:career-scout-api`）會拆分為結構化 tag 項目。不含冒號的 tag 會設為 `true` 值。

## 將 context key 提升為扁平 tag

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

```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` 連線
- 確保在可觀測性配置中將 DatadogBridge 設為 `bridge`（而非 `exporters` 中的項目）
- 確認沒有同時將 `DatadogExporter` 加入 `exporters`：同時使用兩者會重複發出 LLM Observability 數據

有關 `dd-trace` 與 bundler external 的原生模組兼容性問題，請參閱 [Datadog exporter 疑難排解](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/datadog)章節。

## 相關內容

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