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 更简单。它支持 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 相同的数据形状和 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

npm install @mastra/datadog dd-trace

pnpm

pnpm add @mastra/datadog dd-trace

Yarn

yarn add @mastra/datadog dd-trace

Bun

bun add @mastra/datadog dd-trace

Bridge 要求安装 dd-trace，并需要本地 Datadog Agent（或兼容 OTLP receiver）来接收 APM 数据。Agent 设置详情请参阅 exporter 页面中的 APM 前提条件。

配置

使用 DatadogBridge 需要两个步骤：

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

第 1 步：初始化 dd-trace

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

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

// ...

备注

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

第 2 步：Mastra 配置

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

src/mastra/index.ts

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

.env

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。

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。

Trace 层级

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

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 类型映射。

使用标签

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

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 中过滤：

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 故障排除部分。

相关内容

• Tracing 概览
• Datadog Exporter——仅 LLM Observability，不包含 dd-trace APM
• DatadogBridge 参考——API 文档
• Datadog APM 文档
• Datadog LLM Observability 文档