OpenTelemetry bridge

注意

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

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

想在没有现有 OTEL 基础设施的情况下发送 Trace？

如果没有现有 OpenTelemetry 埋点，OpenTelemetry Exporter 可能更简单；它无需设置 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

npm install @mastra/otel-bridge

pnpm

pnpm add @mastra/otel-bridge

Yarn

yarn add @mastra/otel-bridge

Bun

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 文件。它必须在应用代码之前运行：

instrumentation.ts

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 可观测性配置：

src/mastra/index.ts

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：

instrumentation.ts

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 在应用之前加载：

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

语义约定

OtelBridge 使用 OpenTelemetry GenAI 语义约定 v1.38.0 导出 Mastra span。其中包括标准化的 span 名称（chat {model}、execute_tool {tool_name} 等）和属性（gen_ai.usage.input_tokens、gen_ai.request.model 等）。

有关 span 命名和属性的详情，请参阅 OpenTelemetry Exporter 语义约定。

Trace 层级

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

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 上下文会自动传播：

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 时添加标签：

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 概览
• OpenTelemetry Exporter：用于将 Trace 发送到 OTEL 后端
• OtelBridge 参考：API 文档