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

# OpenTelemetry bridge

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

OpenTelemetry（OTEL）Bridge 在 Mastra Tracing 系统和现有 OpenTelemetry 基础设施之间提供双向集成。与将 Trace 数据发送到外部平台的 exporter 不同，bridge 会创建参与分布式 Tracing 上下文的原生 OTEL span。

> **想在没有现有 OTEL 基础设施的情况下发送 Trace？:** 如果没有现有 OpenTelemetry 埋点，[OpenTelemetry Exporter](https://mastra.zisheng.pro/docs/observability/integrations/exporters/otel) 可能更简单；它无需设置 OTEL SDK 即可直接发送 Trace。

## 何时使用 bridge

以下情况请使用 OtelBridge：

- 应用中已有 OTEL 埋点（HTTP server、数据库客户端等）
- 希望 Mastra 操作显示为现有 OTEL Trace 的子 span
- 需要 Mastra Tool 内使用 OTEL 埋点的代码保持正确的父子关系
- 正在构建 Trace 上下文必须跨服务传播的分布式系统

## 工作原理

OtelBridge 提供双向集成：

**从 OTEL 到 Mastra：**

- 自动读取 OTEL ambient context（AsyncLocalStorage）
- 从活跃 OTEL span 继承 Trace ID 和父 span ID
- 遵循 OTEL 采样决策：如果 Trace 未被采样，Mastra 也不会为其创建 span
- 启用 OTEL 自动埋点时，无需手动传递 Trace ID

**从 Mastra 到 OTEL：**

- 为 Mastra 操作（Agent、LLM 调用、Tool、Workflow）创建原生 OTEL span
- 在分布式 Trace 中保持正确的父子关系
- 允许 Mastra 操作内使用 OTEL 埋点的代码（HTTP 客户端、数据库调用）正确嵌套
- 将 Mastra 日志事件转发到全局注册的 OTEL `LoggerProvider`。源自 Mastra span 内部的日志会在该 span 的 OTEL 上下文下发出，以便后端将其与 Trace 关联。如果没有注册 `LoggerProvider`，日志发出会静默地不执行任何操作。

## 安装

**npm**:

```bash
npm install @mastra/otel-bridge
```

**pnpm**:

```bash
pnpm add @mastra/otel-bridge
```

**Yarn**:

```bash
yarn add @mastra/otel-bridge
```

**Bun**:

```bash
bun add @mastra/otel-bridge
```

Bridge 与现有 OpenTelemetry 设置配合工作。根据配置，你可能还需要以下部分软件包：

- `@opentelemetry/sdk-node`——OTEL 的核心 Node.js SDK
- `@opentelemetry/auto-instrumentations-node`——常用库的自动埋点
- `@opentelemetry/exporter-trace-otlp-proto`——OTLP exporter（HTTP 上的 Protobuf）
- `@opentelemetry/exporter-trace-otlp-http`——OTLP exporter（HTTP 上的 JSON）
- `@opentelemetry/exporter-trace-otlp-grpc`——OTLP exporter（gRPC）
- `@opentelemetry/sdk-trace-base`——基础 Tracing SDK（用于 BatchSpanProcessor 等）
- `@opentelemetry/core`——核心工具（用于 W3CTraceContextPropagator 等）
- `@opentelemetry/sdk-logs` 和一个 OTLP 日志 exporter（例如 `@opentelemetry/exporter-logs-otlp-http`）——如果还要 bridge 转发 Mastra 日志事件，则为必需

## 配置

使用 OtelBridge 需要两个步骤：

1. 在应用中配置 OpenTelemetry 埋点
2. 将 OtelBridge 添加到 Mastra 可观测性配置

### 第 1 步：OpenTelemetry 埋点

创建初始化 OTEL 的 instrumentation 文件。它必须在应用代码之前运行：

```typescript
import { NodeSDK } from '@opentelemetry/sdk-node'
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
import { W3CTraceContextPropagator } from '@opentelemetry/core'

const sdk = new NodeSDK({
  serviceName: 'my-service',
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({
        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
      }),
    ),
  ],
  instrumentations: [getNodeAutoInstrumentations()],
  textMapPropagator: new W3CTraceContextPropagator(),
})

sdk.start()

export { sdk }
```

### 第 2 步：Mastra 配置

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

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelBridge } from '@mastra/otel-bridge'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        bridge: new OtelBridge(),
      },
    },
  }),
  agents: {/* your agents */},
})
```

使用 bridge 时不需要 Mastra exporter；Trace 会通过 OTEL SDK 配置发送。如果要将 Trace 发送到其他目标，也可以选择添加 Mastra exporter。

### 转发日志（可选）

Bridge 还会将 Mastra 日志事件转发到全局注册的 OTEL `LoggerProvider`。要同时接入日志和 Trace，请在 `NodeSDK` 上注册 `logRecordProcessor`：

```typescript
import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs'

const sdk = new NodeSDK({
  // ...trace config as usual
  logRecordProcessor: new BatchLogRecordProcessor(
    new OTLPLogExporter({
      url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT || 'http://localhost:4318/v1/logs',
    }),
  ),
})
```

源自 Mastra span 内部的日志会在该 span 的 OTEL 上下文下发出，因此 Datadog、Grafana 和 Honeycomb 等后端会自动将其与周围的 Trace 关联。没有 Trace 上下文的日志使用当前活跃的 OTEL 上下文。

如果没有注册 `LoggerProvider`，日志发出会静默跳过，而 Trace 会继续按配置工作。

### 运行应用

使用 `--import` 标志确保 instrumentation 在应用之前加载：

```bash
tsx --import ./instrumentation.ts ./src/index.ts
```

## 语义约定

OtelBridge 使用 [OpenTelemetry GenAI 语义约定 v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai) 导出 Mastra span。其中包括标准化的 span 名称（`chat {model}`、`execute_tool {tool_name}` 等）和属性（`gen_ai.usage.input_tokens`、`gen_ai.request.model` 等）。

有关 span 命名和属性的详情，请参阅 [OpenTelemetry Exporter 语义约定](https://mastra.zisheng.pro/docs/observability/integrations/exporters/otel)。

## Trace 层级

使用 OtelBridge 后，Trace 可在 OTEL 和 Mastra 边界间保持正确层级：

```text
HTTP POST /api/chat (from Hono middleware)
└── agent.assistant (from Mastra via OtelBridge)
    ├── chat gpt-5.4 (LLM call)
    ├── tool.execute search (tool execution)
    │   └── HTTP GET api.example.com (from OTEL auto-instrumentation)
    └── chat gpt-5.4 (follow-up LLM call)
```

## 多服务分布式 Tracing

OtelBridge 支持 Trace 跨服务边界传播。当服务 A 通过 HTTP 调用服务 B 时，Trace 上下文会自动传播：

```text
Service A: HTTP POST /api/process
└── HTTP POST service-b/api/analyze (outgoing call)

Service B: HTTP POST /api/analyze (incoming call - same trace!)
└── agent.analyzer (Mastra agent inherits trace context)
    └── chat gpt-5.4
```

两个服务都必须具备：

1. 已配置 OTEL 埋点
2. 已启用 W3C Trace Context propagator
3. 已配置带 OtelBridge 的 Mastra

## 使用标签

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

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

为广泛兼容后端，标签会作为 JSON 字符串导出到 `mastra.tags` span 属性。常见用例包括：

- 环境标签：`"production"`、`"staging"`
- 实验跟踪：`"experiment-v1"`、`"control-group"`
- 优先级：`"priority-high"`、`"batch-job"`

## 故障排除

如果 Trace 未按预期显示或连接：

- 确认 OTEL SDK 在 Mastra 之前初始化（使用 `--import` 标志或在入口点顶部导入）
- 确保已将 OtelBridge 添加到可观测性配置
- 检查 OTEL 后端是否运行且可访问

## 相关内容

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [OpenTelemetry Exporter](https://mastra.zisheng.pro/docs/observability/integrations/exporters/otel)：用于将 Trace 发送到 OTEL 后端
- [OtelBridge 参考](https://mastra.zisheng.pro/reference/observability/tracing/bridges/otel)：API 文档