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

# DatadogBridge

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

在 Mastra tracing 与 Datadog 之间实现双向集成。它会实时创建原生 `dd-trace` APM Span，以便 Tool 和处理器中自动埋点的操作正确嵌套在其父 Mastra Span 下。当 Span 结束时，它会通过 `dd-trace` 的 pipeline 发出 LLM Observability 数据。

## 构造函数

```typescript
new DatadogBridge(config?: DatadogBridgeConfig)
```

## `DatadogBridgeConfig`

```typescript
interface DatadogBridgeConfig extends BaseExporterConfig {
  apiKey?: string
  mlApp?: string
  site?: string
  service?: string
  env?: string
  agentless?: boolean
  integrationsEnabled?: boolean
  requestContextKeys?: string[]
}
```

扩展 `BaseExporterConfig`，其中包含：

- `logger?: IMastraLogger` - Logger 实例
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - 日志级别（默认值：INFO）

## 方法

### `createSpan`

```typescript
createSpan(options: CreateSpanOptions<SpanType>): SpanIds | undefined
```

Mastra 可观测性实例在构造 Span 时调用此方法。该方法通过 `tracer.startSpan()` 立即创建 dd-trace APM Span，并返回与 Mastra 兼容的标识符。Mastra 会在 Span 的整个生命周期中使用返回的 ID。dd-trace Span 对象会存储在内部，用于激活 scope。

**返回：** `SpanIds | undefined` - `{ spanId, traceId, parentSpanId }`；如果 Bridge 已禁用，则返回 `undefined`。

### `executeInContext`

```typescript
executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>
```

在 Mastra Span 的 dd-trace 上下文中执行异步函数。函数内运行的 dd-trace 自动埋点操作（HTTP、数据库等）将以此 Span 为父项。

**返回：** `Promise<T>` - 函数执行结果。

### `executeInContextSync`

```typescript
executeInContextSync<T>(spanId: string, fn: () => T): T
```

在 Mastra Span 的 dd-trace 上下文中执行同步函数。

**返回：** `T` - 函数执行结果。

### `flush`

```typescript
async flush(): Promise<void>
```

强制将缓冲区中的所有 LLM Observability 数据刷新到 Datadog，而不关闭 Bridge。适用于需要确保运行时终止前已导出数据的 serverless 环境。

### `shutdown`

```typescript
async shutdown(): Promise<void>
```

强制结束所有未正确关闭的 APM Span，刷新待处理的 LLM Observability 数据，禁用 LLM Observability 集成，并清除所有内部状态。

## 用法示例

### 基本用法

```typescript
import tracer from 'dd-trace'

tracer.init({
  service: process.env.DD_SERVICE || 'my-mastra-app',
  env: process.env.DD_ENV || 'production',
})

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { DatadogBridge } from '@mastra/datadog'

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
      },
    },
  }),
  agents: { myAgent },
})
```

### Agentless 模式（仅 LLM Observability，无本地 Agent）

如果没有本地 Datadog Agent，并且只需要 LLM Observability 数据，请启用 agentless 模式：

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

注意：APM 数据无法在 agentless 模式下发送。如果只需要不含 `dd-trace` APM 的 LLM Observability 数据，[Datadog Exporter](https://mastra.zisheng.pro/reference/observability/tracing/exporters/datadog) 是更简单的选择。

### 与其他 Exporter 结合使用

Bridge 可以与非 Datadog Exporter 结合，将 Trace 发送到其他目标：

```typescript
import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { DatadogBridge } from '@mastra/datadog'

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
        exporters: [
          new MastraStorageExporter(), // Studio access
        ],
      },
    },
  }),
})
```

> **备注:** 不要在同一配置中同时使用 `DatadogBridge` 和 `DatadogExporter`。二者都会向 LLM Observability 发出数据，导致同一数据被重复写入。

## 设置要求

DatadogBridge 要求先于任何其他 import 初始化 `dd-trace`，以便其自动埋点功能可在加载时修补 HTTP、数据库和框架库。

完整设置说明（包括 dd-trace 初始化、bundler externals 和 Agent 配置）请参阅 [DatadogBridge 指南](https://mastra.zisheng.pro/docs/observability/integrations/bridges/datadog)。

## 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`   |
| 所有其他类型             | `task`       |

## 标签支持

`tracingOptions.tags` 值会成为结构化的 LLM Observability annotation 标签：`key:value` 条目会拆分成 key/value 对，不含冒号的标签则设为 `true`。

```typescript
const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'instance_name:career-scout-api'],
  },
})
```

这会生成：

```json
{
  "production": true,
  "instance_name": "career-scout-api"
}
```

## 环境变量

Bridge 从以下环境变量读取配置：

| 变量                            | 说明                                   |
| ----------------------------- | ------------------------------------ |
| `DD_API_KEY`                  | Datadog API key（仅 agentless 模式需要）    |
| `DD_LLMOBS_ML_APP`            | ML 应用名称                              |
| `DD_SITE`                     | Datadog 站点                           |
| `DD_ENV`                      | 环境名称                                 |
| `DD_LLMOBS_AGENTLESS_ENABLED` | 设为 `'true'` 或 `'1'` 以启用 agentless 模式 |

## 相关内容

- [DatadogBridge 指南](https://mastra.zisheng.pro/docs/observability/integrations/bridges/datadog) - 包含示例的设置指南
- [Tracing 概述](https://mastra.zisheng.pro/docs/observability/tracing/overview) - 常规 Tracing 概念
- [DatadogExporter 参考](https://mastra.zisheng.pro/reference/observability/tracing/exporters/datadog) - 仅 LLM Observability，不含 `dd-trace` APM