Datadog 导出器

🌐 Datadog Exporter

Datadog 是一个功能全面的监控平台，具有专门的 LLM 可观测性功能。Datadog 导出器将你的跟踪发送到 Datadog 的 LLM 可观测性产品，提供对模型性能、令牌使用情况和对话流程的洞察。

安装

🌐 Installation

npm

npm install @mastra/datadog@latest

pnpm

pnpm add @mastra/datadog@latest

Yarn

yarn add @mastra/datadog@latest

Bun

bun add @mastra/datadog@latest

配置

🌐 Configuration

先决条件

🌐 Prerequisites

1. Datadog 账户：在 datadoghq.com 注册，并启用 LLM 可观测性
2. API 密钥：从 Datadog 组织设置 → API 密钥 获取你的 API 密钥
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

零配置设置

🌐 Zero-Config Setup

设置环境变量后，使用无配置的导出器：

🌐 With environment variables set, use the exporter with no configuration:

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()],
      },
    },
  }),
});

显式配置

🌐 Explicit Configuration

你也可以直接传递凭据（优先于环境变量）：

🌐 You can also pass credentials directly (takes precedence over environment variables):

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!,
          }),
        ],
      },
    },
  }),
});

配置选项

🌐 Configuration Options

完成配置

🌐 Complete Configuration

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 代理

🌐 With Local Datadog Agent

如果你本地运行了 Datadog Agent，你可以通过它来传输追踪，而不是直接使用 HTTPS：

🌐 If you have a Datadog Agent running locally, you can route traces through it instead of direct HTTPS:

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

注意：使用代理模式时，API 密钥将从本地代理的配置中读取。

🌐 Note: When using agent mode, the API key is read from the local agent's configuration.

跨度类型映射

🌐 Span Type Mapping

Mastra 跨越类型会自动映射到 Datadog LLMObs 跨度类型：

🌐 Mastra span types are automatically mapped to Datadog LLMObs span kinds:

Mastra 跨度类型	Datadog 类型
AGENT_RUN	agent
MODEL_GENERATION	workflow
MODEL_STEP	llm
TOOL_CALL	tool
MCP_TOOL_CALL	tool
WORKFLOW_RUN	workflow
其他工作流类型	task
GENERIC	task

其他/未来的 Mastra 跨类型在映射时默认将是“任务”，除非另有指定。

🌐 Other/future Mastra span types will default to 'task' when mapped unless specified.

故障排除

🌐 Troubleshooting

本地模块 ABI 不匹配

🌐 Native module ABI mismatch

如果你看到类似这样的错误：

🌐 If you see errors like:

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

这表明 Node.js 版本与 dd-trace 的本地模块存在兼容性问题。这些本地模块是可选的，并提供性能监控功能。

🌐 This indicates a Node.js version compatibility issue with dd-trace's native modules. These native modules are optional and provide performance monitoring features.

解决方案:

1. 使用 Node.js 22.x：原生模块与 Node.js 22.x 的兼容性最好。
2. 忽略本地模块警告：本地模块（@datadog/native-metrics、@datadog/native-appsec 等）是可选的。如果加载失败，核心跟踪功能仍然可用。

打包工具外部配置

🌐 Bundler externals configuration

在使用像 esbuild、webpack 或 Mastra CLI 打包工具时，你可能需要将 dd-trace 及其依赖标记为外部依赖：

🌐 When using bundlers like esbuild, webpack, or the Mastra CLI bundler, you may need to mark dd-trace and its dependencies as 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",
    ],
  },
});

相关

🌐 Related

• 追踪概览
• Datadog LLM 可观察性文档