> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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/docs/observability/integrations/bridges/datadog)。Bridge 会实时创建 `dd-trace` span，使 Tool 和 processor 内的 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 key**：从 Datadog Organization Settings → API Keys 获取
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，可以通过它路由 Trace，而不是直接使用 HTTPS：

```typescript
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](https://docs.datadoghq.com/llm_observability/) 集成。要追踪 Mastra HTTP server 路由（请求延迟、错误跟踪、服务地图），请直接使用 `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 软件包**：在项目中安装 Tracing 库：

   **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 路由。这与支持 agentless 模式（通过 HTTPS 直接发送到 Datadog）的 LLM Observability 不同。

### 仅使用 APM

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

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

`dd-trace` 会为常用 HTTP 框架自动埋点，包括 Mastra [server adapter](https://mastra.zisheng.pro/docs/server/server-adapters) 支持的框架。传入请求、传出 HTTP 调用和数据库查询会在 Datadog 中显示为 APM Trace。

### APM 与 LLM Observability

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

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

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

## 故障排除

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

### Bundler external 配置

使用 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',
    ],
  },
})
```

## 相关内容

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [Datadog LLM Observability 文档](https://docs.datadoghq.com/llm_observability/)
- [Datadog APM 文档](https://docs.datadoghq.com/tracing/)