OpenTelemetry 桥

🌐 OpenTelemetry Bridge

warning

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

🌐 The OpenTelemetry Bridge is currently experimental. APIs and configuration options may change in future releases.

OpenTelemetry (OTEL) 桥接器实现了 Mastra 的追踪系统与现有 OpenTelemetry 基础设施之间的双向集成。与将追踪数据发送到外部平台的导出器不同，该桥接器会创建原生 OTEL 跨度，并参与你的分布式追踪上下文。

🌐 The OpenTelemetry (OTEL) Bridge enables bidirectional integration between Mastra's tracing system and existing OpenTelemetry infrastructure. Unlike exporters that send trace data to external platforms, the bridge creates native OTEL spans that participate in your distributed tracing context.

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

如果你没有现有的 OpenTelemetry 检测工具，OpenTelemetry 导出器 可能更简单——它可以直接发送跟踪数据，而无需设置 OTEL SDK。

🌐 If you don't have existing OpenTelemetry instrumentation, the OpenTelemetry Exporter may be simpler — it sends traces directly without requiring an OTEL SDK setup.

何时使用桥梁

🌐 When to Use the Bridge

在以下情况下使用 OtelBridge：

🌐 Use the OtelBridge when you:

• 在你的应用中使用现有的 OTEL 工具（HTTP 服务器、数据库客户端等）
• 希望 Mastra 操作显示为你现有 OTEL 跟踪的子跨度
• 需要在 Mastra 工具中使用 OTEL 仪表化的代码以保持正确的父子关系
• 正在构建一个分布式系统，其中追踪上下文必须在各个服务之间传播

工作原理

🌐 How It Works

OtelBridge 提供双向集成：

🌐 The OtelBridge provides two-way integration:

从 OTEL 到 Mastra：

• 自动从 OTEL 环境上下文（AsyncLocalStorage）读取
• 继承活动 OTEL 追踪的追踪 ID 和父跨度 ID
• 尊重 OTEL 的采样决策——如果一个跟踪未被采样，Mastra 不会为其创建跨度
• 当 OTEL 自动监控启用时，无需手动传递 trace ID

从Mastra到OTEL：

• 为 Mastra 操作（代理、LLM 调用、工具、工作流）创建本地 OTEL span
• 在分布式追踪中保持正确的父子关系
• 允许在 Mastra 操作中使用 OTEL 仪表的代码（HTTP 客户端、数据库调用）正确嵌套

安装

🌐 Installation

npm

npm install @mastra/otel-bridge

pnpm

pnpm add @mastra/otel-bridge

Yarn

yarn add @mastra/otel-bridge

Bun

bun add @mastra/otel-bridge

该桥接可以与你现有的 OpenTelemetry 设置配合使用。根据你的配置，你可能还需要以下一些软件包：

🌐 The bridge works with your existing OpenTelemetry setup. Depending on your configuration, you may also need some of these packages:

• @opentelemetry/sdk-node - OTEL 的核心 Node.js SDK
• @opentelemetry/auto-instrumentations-node - 常用库的自动检测
• @opentelemetry/exporter-trace-otlp-proto - OTLP 导出器（基于 HTTP 的 Protobuf）
• @opentelemetry/exporter-trace-otlp-http - OTLP 导出器（通过 HTTP 的 JSON）
• @opentelemetry/exporter-trace-otlp-grpc - OTLP 导出器（gRPC）
• @opentelemetry/sdk-trace-base - 基础追踪 SDK（用于 BatchSpanProcessor 等）
• @opentelemetry/core - 核心工具（用于 W3CTraceContextPropagator 等）

配置

🌐 Configuration

使用 OtelBridge 需要两个步骤：

🌐 Using the OtelBridge requires two steps:

1. 在你的应用中配置 OpenTelemetry 仪表
2. 将 OtelBridge 添加到你的 Mastra 可观测性配置中

步骤 1：OpenTelemetry 仪器化

🌐 Step 1: OpenTelemetry Instrumentation

创建一个初始化 OTEL 的监控文件。这必须在你的应用代码之前运行：

🌐 Create an instrumentation file that initializes OTEL. This must run before your application code:

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 配置

🌐 Step 2: Mastra Configuration

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

🌐 Add the OtelBridge to your Mastra observability config:

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 */
  },
});

使用桥接时不需要 Mastra 导出器——追踪通过你的 OTEL SDK 配置发送。如果你希望将追踪发送到其他目的地，也可以选择添加 Mastra 导出器。

🌐 No Mastra exporters are required when using the bridge — traces are sent via your OTEL SDK configuration. You can optionally add Mastra exporters if you want to send traces to additional destinations.

运行你的应用

🌐 Running Your Application

使用 --import 标志以确保在你的应用加载之前加载检测工具：

🌐 Use the --import flag to ensure instrumentation loads before your application:

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

语义约定

🌐 Semantic Conventions

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

🌐 The OtelBridge exports Mastra spans using OpenTelemetry Semantic Conventions for GenAI v1.38.0. This includes standardized span names (chat {model}, execute_tool {tool_name}, etc.) and attributes (gen_ai.usage.input_tokens, gen_ai.request.model, etc.).

有关跨度命名和属性的详细信息，请参阅 OpenTelemetry 导出器语义约定。

🌐 For details on span naming and attributes, see the OpenTelemetry Exporter semantic conventions.

追踪层级

🌐 Trace Hierarchy

使用 OtelBridge，你的跟踪在 OTEL 和 Mastra 边界之间保持正确的层次结构：

🌐 With the OtelBridge, your traces maintain proper hierarchy across OTEL and Mastra boundaries:

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

多服务分布式追踪

🌐 Multi-Service Distributed Tracing

OtelBridge 可实现跨服务边界的追踪传播。当服务 A 通过 HTTP 调用服务 B 时，追踪上下文会自动传播：

🌐 The OtelBridge enables trace propagation across service boundaries. When Service A calls Service B via HTTP, trace context propagates automatically:

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-4o

两项服务必须具有：

🌐 Both services must have:

1. 已配置 OTEL 仪表化
2. 已启用 W3C Trace Context 传播器
3. 已配置 OtelBridge 的 Mastra

使用标签

🌐 Using Tags

标签可以帮助你在 OTEL 后端对跟踪进行分类和筛选。在执行代理或工作流时添加标签：

🌐 Tags help you categorize and filter traces in your OTEL backend. Add tags when executing agents or workflows:

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

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

🌐 Tags are exported as a JSON string in the mastra.tags span attribute for broad backend compatibility. Common use cases include:

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

故障排除

🌐 Troubleshooting

如果痕迹没有按预期出现或连接：

🌐 If traces aren't appearing or connecting as expected:

• 在 Mastra 之前验证 OTEL SDK 是否已初始化（使用 --import 标志或在入口点顶部导入）
• 确保将 OtelBridge 添加到你的可观察性配置中
• 检查你的 OTEL 后端是否正在运行并且可以访问

相关

🌐 Related

• 追踪概览
• OpenTelemetry 导出器 - 用于将追踪发送到 OTEL 后端
• OtelBridge 参考 - API 文档