OtelBridge

warning

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

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

实现 Mastra 跟踪与 OpenTelemetry 基础设施之间的双向集成。为 Mastra 操作创建原生 OTEL 跨度，并从活动 OTEL 跨度继承上下文。

🌐 Enables bidirectional integration between Mastra tracing and OpenTelemetry infrastructure. Creates native OTEL spans for Mastra operations and inherits context from active OTEL spans.

构造函数

🌐 Constructor

new OtelBridge()

方法

🌐 Methods

executeInContext

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

在 Mastra span 的 OTEL 上下文中执行异步函数。在函数内运行的 OTEL 仪表化代码将具有正确的父子关系。

🌐 Executes an async function within the OTEL context of a Mastra span. OTEL-instrumented code running inside the function will have correct parent relationships.

返回值: Promise<T> - 函数执行的结果。

executeInContextSync

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

在 Mastra 跨度的 OTEL 上下文中执行同步函数。

🌐 Executes a synchronous function within the OTEL context of a Mastra span.

返回值: T - 函数执行的结果。

shutdown

async shutdown(): Promise<void>

关闭桥接并清理资源。结束任何未正确关闭的跨度。

🌐 Shuts down the bridge and cleans up resources. Ends any spans that were not properly closed.

使用示例

🌐 Usage Examples

基本用法

🌐 Basic Usage

import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { OtelBridge } from "@mastra/otel-bridge";

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: "my-service",
        bridge: new OtelBridge(),
      },
    },
  }),
  agents: { myAgent },
});

与导出器合作

🌐 Combined with Exporters

该桥可以与导出器一起使用。桥处理 OTEL 上下文，而导出器将数据发送到其他目的地：

🌐 The bridge can be used alongside exporters. The bridge handles OTEL context, while exporters send data to additional destinations:

import { Mastra } from "@mastra/core";
import { Observability, DefaultExporter } from "@mastra/observability";
import { OtelBridge } from "@mastra/otel-bridge";
import { LangfuseExporter } from "@mastra/langfuse";

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: "my-service",
        bridge: new OtelBridge(), // Handles OTEL context
        exporters: [
          new DefaultExporter(), // Studio access
          new LangfuseExporter({
            // Additional destination
            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
            secretKey: process.env.LANGFUSE_SECRET_KEY,
          }),
        ],
      },
    },
  }),
});

OpenTelemetry 设置要求

🌐 OpenTelemetry Setup Requirements

OtelBridge 需要一个活跃的 OpenTelemetry SDK 才能运行。该桥接器从 OTEL 的环境上下文中读取数据。

🌐 The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.

请参阅 OtelBridge 指南 以获取完整的设置说明，包括如何配置 OTEL 仪表和运行你的应用。

🌐 See the OtelBridge Guide for complete setup instructions, including how to configure OTEL instrumentation and run your application.

标签支持

🌐 Tags Support

OtelBridge 支持用于分类和过滤的追踪标签。标签仅应用于根跨度，并作为原生 OTEL 跨度上的 mastra.tags 属性包含。

🌐 The OtelBridge supports trace tagging for categorization and filtering. Tags are only applied to root spans and are included as the mastra.tags attribute on native OTEL spans.

用法

🌐 Usage

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

标签的存储方式

🌐 How Tags Are Stored

标签以 JSON 字符串化的数组形式存储在 mastra.tags 的 span 属性中：

🌐 Tags are stored as a JSON-stringified array in the mastra.tags span attribute:

{
  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
}

该格式确保与所有 OTEL 兼容的后端和收集器兼容。

🌐 This format ensures compatibility with all OTEL-compatible backends and collectors.

相关

🌐 Related

• OtelBridge 指南 - 带示例的设置指南
• 跟踪概览 - 一般跟踪概念
• OtelExporter 参考 - 用于发送追踪的 OTEL 导出器