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

# Datadog bridge

> **注意:** Datadog Bridge 目前处于**实验阶段**。API 和配置选项可能会在未来版本中发生变化。

Datadog Bridge 在 Mastra Tracing 系统和 Datadog 之间提供双向集成。与在执行完成后发送 Trace 数据的 exporter 不同，bridge 会实时创建原生 dd-trace span，使 Tool 和 processor 内由 APM 自动埋点的操作（HTTP 调用、数据库查询等）正确嵌套在其父 Mastra span 下。

> **没有使用 dd-trace APM？:** 如果只需要发送 LLM Observability 数据，且不使用 `dd-trace` APM 自动埋点，[Datadog Exporter](https://mastra.zisheng.pro/docs/observability/integrations/exporters/datadog) 更简单。它支持 agentless 模式，无需本地 Agent 即可将 span 直接发送到 Datadog。

## 何时使用 bridge

以下情况请使用 DatadogBridge：

- 应用中使用 `dd-trace` 自动埋点（HTTP server、数据库客户端等）
- 希望 Tool、MCP Tool 或输出 processor 发出的 APM 服务调用显示在其父 Mastra span 下，而不是请求处理程序下
- 需要 APM Trace 和 LLM Observability 数据共享一致的 Trace 拓扑
- 正在构建 Datadog Trace 上下文必须跨服务传播的分布式系统

## 工作原理

DatadogBridge 参与 dd-trace 管道的两个部分：

**APM 上下文传播（实时）：**

- 创建每个 Mastra span 时，通过 `tracer.startSpan()` 创建 dd-trace APM span
- 执行期间通过 `tracer.scope().activate()` 在 dd-trace scope 中激活 APM span
- 活跃 scope 内的自动埋点操作会以正确的 Mastra span 为父 span
- 没有显式 Mastra 父 span 时，继承活跃 dd-trace 上下文（例如传入请求 span）

**LLM Observability 发出（span 结束时）：**

- 通过 `dd-trace` 的 LLM Observability 管道发出注释（模型信息、token 用量、输入/输出、错误）
- 使用嵌套 `llmobs.trace()` 调用在 Datadog LLM Observability 中保持父子关系
- 复用与 [Datadog Exporter](https://mastra.zisheng.pro/docs/observability/integrations/exporters/datadog) 相同的数据形状和 span kind 映射

## Trace 与日志关联

如果不使用 bridge，Datadog Exporter 只会在 Trace 完成后创建 LLM Observability span。执行期间，scope 中没有活跃的 `dd-trace` span，因此 Tool 发出的 HTTP 或数据库调用会回退到当时活跃的任意 `dd-trace` span，通常是传入请求处理程序。结果是 MCP Tool 或输出 processor 的服务调用显示为请求 span 的子项，而不是实际发出调用的 Agent 或 processor span 的子项。

Bridge 会预先创建真正的 dd-trace span，从而在自动埋点运行时使用正确的 scope，解决这一问题。

## 安装

**npm**:

```bash
npm install @mastra/datadog dd-trace
```

**pnpm**:

```bash
pnpm add @mastra/datadog dd-trace
```

**Yarn**:

```bash
yarn add @mastra/datadog dd-trace
```

**Bun**:

```bash
bun add @mastra/datadog dd-trace
```

Bridge 要求安装 `dd-trace`，并需要本地 Datadog Agent（或兼容 OTLP receiver）来接收 APM 数据。Agent 设置详情请参阅 exporter 页面中的 [APM 前提条件](https://mastra.zisheng.pro/docs/observability/integrations/exporters/datadog)。

## 配置

使用 DatadogBridge 需要两个步骤：

1. 初始化 `dd-trace`，使其自动埋点能够 patch HTTP、数据库和框架库
2. 将 DatadogBridge 添加到 Mastra 可观测性配置

### 第 1 步：初始化 dd-trace

`dd-trace` 必须在其他任何 import 之前初始化，以便其自动埋点在加载时 patch 各个库。Bridge 会检测已初始化的 tracer 并复用它。

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

// ...
```

> **备注:** 请在应用入口文件的最顶部、其他任何 import 之前导入并初始化 `dd-trace`。

### 第 2 步：Mastra 配置

将 DatadogBridge 添加到 Mastra 可观测性配置：

```typescript
export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
      },
    },
  }),
  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_LLMOBS_ML_APP=my-llm-app
```

初始化 `dd-trace` 后，它会将 APM 数据路由到 `localhost:8126` 上的本地 Datadog Agent。Bridge 会在同一 tracer 上启用 LLM Observability，因此两组数据会出现在 Datadog 的同一服务下。

使用 bridge 时不需要 Mastra exporter；APM 和 LLM Observability 数据都通过 `dd-trace` 流动。如果要将 Trace 发送到其他目标，仍可添加 Mastra exporter。

## Agent 模式与 agentless 模式

Bridge 默认为 **Agent 模式**（`agentless: false`）。该模式假设本地 Datadog Agent 在 `localhost:8126` 运行，并接收 APM 和 LLM Observability 数据。使用 `dd-trace` 自动埋点时通常采用此设置，因为 APM 数据始终通过 Agent 路由。

如果没有本地 Datadog Agent 且只需要 LLM Observability 数据（不使用 APM 自动埋点），可启用 agentless 模式，直接将数据发送到 Datadog。此时必须提供 API key。

```typescript
new DatadogBridge({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  apiKey: process.env.DD_API_KEY!,
  agentless: true,
})
```

> **备注:** 对于大多数 bridge 用户，Agent 模式是正确选择。APM 数据不能以 agentless 模式发送，因此启用 agentless 会使 LLM Observability 流量与 APM 流量分离。如果只需要无 Agent 的 LLM Observability，请改用 [Datadog Exporter](https://mastra.zisheng.pro/docs/observability/integrations/exporters/datadog)。

## Trace 层级

使用 DatadogBridge 后，Trace 可在 dd-trace 和 Mastra 边界间保持正确层级。Tool 和 processor 发出的服务调用会显示在正确的 Mastra span 下：

```text
HTTP POST /api/chat (from web framework instrumentation)
└── agent.orchestrator (from Mastra via DatadogBridge)
    ├── chat gpt-5.4 (LLM call)
    ├── tool.execute search (tool execution)
    │   └── HTTP GET api.example.com (auto-instrumented from inside the tool)
    └── processor.guardrail (output processor)
        └── HTTP POST guardrail-service/check (auto-instrumented from inside the processor)
```

在 Datadog 中，APM Trace 会显示这个完整拓扑，而 LLM Observability 产品会显示 Agent 和 LLM 专用 span 及其输入、输出和 token 指标。

## Span 类型映射

Bridge 对 LLM Observability 使用与 Datadog Exporter 相同的 span kind 映射。请参阅 exporter 页面的 [span 类型映射](https://mastra.zisheng.pro/docs/observability/integrations/exporters/datadog)。

## 使用标签

标签有助于在 Datadog 中对 Trace 分类和过滤。执行 Agent 或 Workflow 时添加标签：

```typescript
const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'experiment-v2', 'user-request'],
  },
})
```

格式为 `key:value` 的标签（例如 `instance_name:career-scout-api`）会拆分为结构化标签项。不含冒号的标签会被设为值 `true`。

## 将上下文键提升为扁平标签

使用 `requestContextKeys` 将 request context 或 span 属性中的特定键提升为扁平、可索引的 LLM Observability 标签，使其可在 Datadog UI 中过滤：

```typescript
new DatadogBridge({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  requestContextKeys: ['tenantId', 'agentId'],
})
```

提升的键会从 `annotations.metadata` 中移除，并作为扁平标签添加到每个 LLM Observability span。

## 故障排除

如果 APM span 没有按预期连接到 Mastra span：

- 确认 `dd-trace` 在其他任何 import **之前**初始化（它会在加载时 patch 库）
- 确认本地 Datadog Agent 正在运行，且可通过 `localhost:8126` 访问
- 确保在可观测性配置中将 DatadogBridge 设为 `bridge`，而不是 `exporters` 中的一项
- 确认没有同时将 `DatadogExporter` 添加到 `exporters`；同时使用两者会重复发出 LLM Observability 数据

有关 `dd-trace` 和 bundler external 的原生模块兼容性问题，请参阅 [Datadog exporter 故障排除](https://mastra.zisheng.pro/docs/observability/integrations/exporters/datadog)部分。

## 相关内容

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [Datadog Exporter](https://mastra.zisheng.pro/docs/observability/integrations/exporters/datadog)——仅 LLM Observability，不包含 `dd-trace` APM
- [DatadogBridge 参考](https://mastra.zisheng.pro/reference/observability/tracing/bridges/datadog)——API 文档
- [Datadog APM 文档](https://docs.datadoghq.com/tracing/)
- [Datadog LLM Observability 文档](https://docs.datadoghq.com/llm_observability/)