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

# Datadog exporter

[Datadog](https://datadoghq.com/) 是一個功能完整的監控平台，提供專門的 LLM Observability 功能。Datadog exporter 會將你的 Trace 傳送至 Datadog 的 LLM Observability 產品，讓你深入了解模型效能、token 使用量及對話流程。

> **同時使用 dd-trace APM？:** 如果你同時使用 `dd-trace` APM 自動檢測，建議改用 [Datadog Bridge](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/bridges/datadog)。Bridge 會即時建立 `dd-trace` span，讓 Tool 和處理器內的 HTTP 及數據庫呼叫正確巢狀置於其父 Mastra span 之下。單獨使用 exporter 只會在執行完成後傳送 LLM Observability 數據，因此自動檢測的 APM span 會回退至請求處理程式。

## 安裝

**npm**:

```bash
npm install @mastra/datadog@latest
```

**pnpm**:

```bash
pnpm add @mastra/datadog@latest
```

**Yarn**:

```bash
yarn add @mastra/datadog@latest
```

**Bun**:

```bash
bun add @mastra/datadog@latest
```

## 配置

### 先決條件

1. **Datadog 帳戶**：在已啟用 LLM Observability 的 [datadoghq.com](https://datadoghq.com/) 註冊
2. **API 金鑰**：前往 Datadog Organization Settings → API Keys 取得 API 金鑰
3. **環境變數**：設定你的憑證

```bash
DD_API_KEY=your-datadog-api-key
DD_LLMOBS_ML_APP=my-llm-app
DD_SITE=datadoghq.com  # Optional: defaults to datadoghq.com
DD_ENV=production      # Optional: environment name
```

### 零配置設定

設定環境變數後，無需任何配置即可使用 exporter：

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { DatadogExporter } from '@mastra/datadog'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      datadog: {
        serviceName: 'my-service',
        exporters: [new DatadogExporter()],
      },
    },
  }),
})
```

### 明確配置

你亦可直接傳入憑證（其優先級高於環境變數）：

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { DatadogExporter } from '@mastra/datadog'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      datadog: {
        serviceName: 'my-service',
        exporters: [
          new DatadogExporter({
            mlApp: process.env.DD_LLMOBS_ML_APP!,
            apiKey: process.env.DD_API_KEY!,
          }),
        ],
      },
    },
  }),
})
```

## 配置選項

### 完整配置

```typescript
new DatadogExporter({
  // Required settings
  mlApp: process.env.DD_LLMOBS_ML_APP!, // Groups traces under this ML app name
  apiKey: process.env.DD_API_KEY!, // Required for agentless mode (default)

  // Optional settings
  site: 'datadoghq.com', // Datadog site (datadoghq.eu, us3.datadoghq.com, etc.)
  service: 'my-service', // Service name (defaults to mlApp)
  env: 'production', // Environment name
  agentless: true, // true = direct HTTPS, false = local Datadog Agent

  // Advanced settings
  integrationsEnabled: false, // Enable dd-trace auto-instrumentation

  // Diagnostic logging
  logLevel: 'info', // debug | info | warn | error
})
```

### 配合本機 Datadog Agent 使用

如果本機正在執行 Datadog Agent，你可以透過該 Agent 路由 Trace，而非直接使用 HTTPS：

```typescript
new DatadogExporter({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  agentless: false, // Use local Datadog Agent
  env: 'production',
})
```

注意：使用 Agent 模式時，API 金鑰會從本機 Agent 的配置中讀取。

## Span 類型映射

Mastra span 類型會自動映射至 Datadog LLM Observability span 種類：

| Mastra SpanType    | Datadog 種類 |
| ------------------ | ---------- |
| `AGENT_RUN`        | `agent`    |
| `MODEL_GENERATION` | `workflow` |
| `MODEL_STEP`       | `llm`      |
| `TOOL_CALL`        | `tool`     |
| `MCP_TOOL_CALL`    | `tool`     |
| `WORKFLOW_RUN`     | `workflow` |
| 其他 Workflow 類型     | `task`     |
| `GENERIC`          | `task`     |

除非另有指定，其他或日後新增的 Mastra span 類型在映射時會預設為 'task'。

## 應用程式效能監控

以上章節介紹 Mastra 的 [LLM Observability](https://docs.datadoghq.com/llm_observability/) 整合。如要追蹤 Mastra HTTP 伺服器路由（請求延遲、錯誤追蹤、服務地圖），請直接使用 `dd-trace` 進行 Datadog Application Performance Monitoring (APM)。

### 先決條件

1. **Datadog Agent**：在同一主機安裝 [Datadog Agent](https://docs.datadoghq.com/agent/)，或確保可經網絡存取。Agent 會在 `localhost:8126` 接收來自 `dd-trace` 的 Trace，並將其轉送至 Datadog。請按照 [Agent 安裝指南](https://docs.datadoghq.com/agent/) 完成設定。

2. **dd-trace 依賴套件**：在你的項目中安裝追蹤依賴套件：

   **npm**:

   ```bash
   npm install dd-trace
   ```

   **pnpm**:

   ```bash
   pnpm add dd-trace
   ```

   **Yarn**:

   ```bash
   yarn add dd-trace
   ```

   **Bun**:

   ```bash
   bun add dd-trace
   ```

> **備註:** APM Trace 一律透過 Datadog Agent 路由。這與支援無 Agent 模式（直接以 HTTPS 傳送至 Datadog）的 LLM Observability 不同。

### 僅使用 APM

在進入點檔案頂部、任何其他 import 之前，import 並初始化 `dd-trace`：

```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'

export const mastra = new Mastra({
  bundler: {
    externals: [
      'dd-trace',
      '@datadog/native-metrics',
      '@datadog/native-appsec',
      '@datadog/native-iast-taint-tracking',
      '@datadog/pprof',
    ],
  },
})
```

設定 tracer metadata 環境變數：

```bash
DD_SERVICE=my-mastra-app
DD_ENV=production
DD_VERSION=1.0.0
```

`dd-trace` 會自動檢測常用的 HTTP framework，包括 Mastra [伺服器配接器](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters)所支援的 framework。傳入請求、傳出 HTTP 呼叫及數據庫查詢會在 Datadog 中顯示為 APM Trace。

### APM 與 LLM Observability

建立 Mastra 實例前，先 import 並初始化 `dd-trace`。`DatadogExporter` 會偵測現有的 tracer 並略過重新初始化，在你的 APM 設定上加入 LLM Observability：

```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 { DatadogExporter } from '@mastra/datadog'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      datadog: {
        serviceName: 'my-mastra-app',
        exporters: [
          new DatadogExporter({
            mlApp: process.env.DD_LLMOBS_ML_APP!,
            apiKey: process.env.DD_API_KEY!,
          }),
        ],
      },
    },
  }),
  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_API_KEY=your-datadog-api-key
DD_LLMOBS_ML_APP=my-llm-app
```

伺服器路由會顯示為 APM Trace，而 LLM 呼叫會顯示為 LLM Observability span，全部歸於 Datadog 中的同一服務。

> **備註:** 請在所有其他模組之前 import 並初始化 `dd-trace`，讓其自動檢測功能可在載入時修補 HTTP、數據庫及 framework 依賴套件。

## 疑難排解

### 原生模組 ABI 不相符

如果你看到如下錯誤：

```text
Error: No native build was found for runtime=node abi=137 platform=linuxglibc arch=x64
```

這表示 `dd-trace` 的原生模組與 Node.js 版本之間存在兼容性問題。這些原生模組為**選用**，並提供效能監控功能。

**解決方法：**

1. **使用 Node.js 22.x**：原生模組與 Node.js 22.x 的兼容性最佳。

2. **忽略原生模組警告**：原生模組（`@datadog/native-metrics`、`@datadog/native-appsec` 等）為選用。即使無法載入，核心追蹤功能仍可正常運作。

### Bundler externals 配置

使用 esbuild、webpack 或 Mastra CLI bundler 等 bundler 時，你可能需要將 `dd-trace` 及其依賴套件標記為 external：

```typescript
export const mastra = new Mastra({
  bundler: {
    externals: [
      'dd-trace',
      '@datadog/native-metrics',
      '@datadog/native-appsec',
      '@datadog/native-iast-taint-tracking',
      '@datadog/pprof',
    ],
  },
})
```

## 相關內容

- [Trace 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)
- [Datadog LLM Observability 文件](https://docs.datadoghq.com/llm_observability/)
- [Datadog APM 文件](https://docs.datadoghq.com/tracing/)