Datadog exporter

Datadog 是一个完整的监控平台，提供专门的 LLM Observability 功能。Datadog exporter 会将 Trace 发送到 Datadog 的 LLM Observability 产品，帮助你深入了解模型性能、token 用量和对话流程。

还在使用 dd-trace APM？

如果还使用 dd-trace APM 自动埋点，请考虑改用 Datadog Bridge。Bridge 会实时创建 dd-trace span，使 Tool 和 processor 内的 HTTP 与数据库调用正确嵌套在父 Mastra span 下。单独使用 exporter 时，会在执行完成后才发送 LLM Observability 数据，这意味着自动埋点的 APM span 会回退到请求处理程序。

安装

npm

npm install @mastra/datadog@latest

pnpm

pnpm add @mastra/datadog@latest

Yarn

yarn add @mastra/datadog@latest

Bun

bun add @mastra/datadog@latest

配置

前提条件

1. Datadog 账户：在启用 LLM Observability 的 datadoghq.com 注册
2. API key：从 Datadog Organization Settings → API Keys 获取
3. 环境变量：设置凭据

.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，可以通过它路由 Trace，而不是直接使用 HTTPS：

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

注意：使用 Agent 模式时，API key 会从本地 Agent 配置中读取。

Span 类型映射

Mastra span 类型会自动映射到 Datadog LLM Observability span kind：

Mastra SpanType	Datadog Kind
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 路由（请求延迟、错误跟踪、服务地图），请直接使用 dd-trace 进行 Datadog Application Performance Monitoring（APM）。

前提条件

1. Datadog Agent：在同一主机上安装 Datadog Agent，或确保可通过网络访问。Agent 会在 localhost:8126 接收来自 dd-trace 的 Trace，并将其转发到 Datadog。按照 Agent 安装指南进行设置。

2. dd-trace 软件包：在项目中安装 Tracing 库：

   npm

   npm install dd-trace

   pnpm

   pnpm add dd-trace

   Yarn

   yarn add dd-trace

   Bun

   bun add dd-trace

备注

APM Trace 始终通过 Datadog Agent 路由。这与支持 agentless 模式（通过 HTTPS 直接发送到 Datadog）的 LLM Observability 不同。

仅使用 APM

在入口文件顶部、其他任何 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 元数据环境变量：

.env

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

dd-trace 会为常用 HTTP 框架自动埋点，包括 Mastra server adapter 支持的框架。传入请求、传出 HTTP 调用和数据库查询会在 Datadog 中显示为 APM Trace。

APM 与 LLM Observability

在创建 Mastra 实例之前导入并初始化 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

Server 路由会显示为 APM Trace，LLM 调用会显示为 LLM Observability span，并且都位于 Datadog 的同一服务下。

备注

在其他所有模块之前导入并初始化 dd-trace。这样，它的自动埋点可以在加载时 patch HTTP、数据库和框架库。

故障排除

原生模块 ABI 不匹配

如果看到如下错误：

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 等）是可选的。即使加载失败，核心 Tracing 功能仍可正常工作。

Bundler external 配置

使用 esbuild、webpack 或 Mastra CLI bundler 等 bundler 时，可能需要将 dd-trace 及其依赖标记为 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',
    ],
  },
})

相关内容

• Tracing 概览
• Datadog LLM Observability 文档
• Datadog APM 文档