Datadog Exporter

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

同時使用 dd-trace APM？

如果你同時使用 dd-trace APM 自動 instrumentation，建議改用 Datadog Bridge。Bridge 會即時建立 dd-trace span，讓 Tool 和 Processor 內的 HTTP 及資料庫呼叫正確巢狀置於其父 Mastra span 之下。單獨使用 Exporter 只會在執行完成後傳送 LLM Observability 資料，因此自動 instrumentation 的 APM span 會回退至 request handler。

安裝
「安裝」的直接連結

npm
pnpm
Yarn
Bun

npm install @mastra/datadog@latest

pnpm add @mastra/datadog@latest

yarn add @mastra/datadog@latest

bun add @mastra/datadog@latest

設定
「設定」的直接連結

先決條件
「先決條件」的直接連結

Datadog 帳戶：在已啟用 LLM Observability 的 datadoghq.com 註冊
API 金鑰：前往 Datadog Organization Settings → API Keys 取得 API 金鑰
環境變數：設定你的憑證

.env
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：

src/mastra/index.ts
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()],
      },
    },
  }),
})

明確設定
「明確設定」的直接連結

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

src/mastra/index.ts
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!,
          }),
        ],
      },
    },
  }),
})

設定選項
「設定選項」的直接連結

完整設定
「完整設定」的直接連結

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 使用」的直接連結

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

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

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

Span 類型映射
「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 整合。如要追蹤 Mastra HTTP Server 路由（request 延遲、錯誤追蹤、服務地圖），請直接使用 dd-trace 進行 Datadog Application Performance Monitoring (APM)。

先決條件
「先決條件」的直接連結

Datadog Agent：在同一主機安裝 Datadog Agent，或確保可透過網路存取。Agent 會在 localhost:8126 接收來自 dd-trace 的 Trace，並將其轉送至 Datadog。請按照 Agent 安裝指南完成設定。

dd-trace 套件：在你的專案中安裝 Tracing library：

npm
pnpm
Yarn
Bun

npm install dd-trace

pnpm add dd-trace

yarn add dd-trace

bun add dd-trace

備註

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

僅使用 APM
「僅使用 APM」的直接連結

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

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'

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

設定 tracer metadata 環境變數：

.env
DD_SERVICE=my-mastra-app
DD_ENV=production
DD_VERSION=1.0.0

dd-trace 會自動 instrumentation 常用的 HTTP framework，包括 Mastra Server adapter 所支援的 framework。傳入 request、傳出 HTTP 呼叫及資料庫查詢會在 Datadog 中顯示為 APM Trace。

APM 與 LLM Observability
「APM 與 LLM Observability」的直接連結

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

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

.env
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，讓其自動 instrumentation 功能可在載入時 patch HTTP、資料庫及 framework dependency。

疑難排解
「疑難排解」的直接連結

原生模組 ABI 不相符
「原生模組 ABI 不相符」的直接連結

如果你看到如下錯誤：

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

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

解決方法：

使用 Node.js 22.x：原生模組與 Node.js 22.x 的相容性最佳。
忽略原生模組警告：原生模組（@datadog/native-metrics、@datadog/native-appsec 等）為選用。即使無法載入，核心追蹤功能仍可正常運作。

Bundler externals 設定
「Bundler externals 設定」的直接連結

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

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

安裝「安裝」的直接連結

設定「設定」的直接連結

先決條件「先決條件」的直接連結

零設定設定「零設定設定」的直接連結

明確設定「明確設定」的直接連結

設定選項「設定選項」的直接連結

完整設定「完整設定」的直接連結

配合本機 Datadog Agent 使用「配合本機 Datadog Agent 使用」的直接連結

Span 類型映射「Span 類型映射」的直接連結

應用程式效能監控「應用程式效能監控」的直接連結

先決條件「先決條件」的直接連結

僅使用 APM「僅使用 APM」的直接連結

APM 與 LLM Observability「APM 與 LLM Observability」的直接連結

疑難排解「疑難排解」的直接連結

原生模組 ABI 不相符「原生模組 ABI 不相符」的直接連結

Bundler externals 設定「Bundler externals 設定」的直接連結

相關內容「相關內容」的直接連結

安裝
「安裝」的直接連結

設定
「設定」的直接連結

先決條件
「先決條件」的直接連結

零設定設定
「零設定設定」的直接連結

明確設定
「明確設定」的直接連結

設定選項
「設定選項」的直接連結

完整設定
「完整設定」的直接連結

配合本機 Datadog Agent 使用
「配合本機 Datadog Agent 使用」的直接連結

Span 類型映射
「Span 類型映射」的直接連結

應用程式效能監控
「應用程式效能監控」的直接連結

先決條件
「先決條件」的直接連結

僅使用 APM
「僅使用 APM」的直接連結

APM 與 LLM Observability
「APM 與 LLM Observability」的直接連結

疑難排解
「疑難排解」的直接連結

原生模組 ABI 不相符
「原生模組 ABI 不相符」的直接連結

Bundler externals 設定
「Bundler externals 設定」的直接連結

相關內容
「相關內容」的直接連結