OtelBridge

注意

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

在 Mastra tracing 与 OpenTelemetry 基础设施之间实现双向集成。它为 Mastra 操作创建原生 OTEL Span，并从活动 OTEL Span 继承上下文。它还会将 Mastra 日志事件转发到全局注册的 OTEL LoggerProvider，在原始 Mastra Span 的 OTEL 上下文中发出每条日志，从而自动实现 Trace 与日志的关联。

构造函数

new OtelBridge()

方法

executeInContext

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

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

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

executeInContextSync

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

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

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

onLogEvent

async onLogEvent(event: LogEvent): Promise<void>

将 Mastra 日志事件转发到全局注册的 OTEL LoggerProvider。Trace 关联按以下顺序解析：

1. 如果日志携带的 spanId 对应 Bridge 已有的 OTEL Span，则在该 Span 存储的 OTEL 上下文中发出日志。
2. 否则，如果日志携带 traceId 和 spanId，则将这些 ID 附加到所发出日志记录的 SpanContext。
3. 否则，在当前活动的 OTEL 上下文中发出日志。

如果没有全局注册 LoggerProvider，则不会发出内容，也不会提示。

flush

async flush(): Promise<void>

如果全局 OTEL tracer Provider 和 logger Provider 支持 forceFlush，则强制刷新它们。适用于需要在运行时终止前清空遥测数据的 serverless 环境。

shutdown

async shutdown(): Promise<void>

关闭 Bridge 并清理资源。结束所有未正确关闭的 Span。

用法示例

基本用法

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 },
})

与 Exporter 结合使用

Bridge 可以与 Exporter 一起使用。Bridge 负责处理 OTEL 上下文，而 Exporter 将数据发送到其他目标：

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } 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 MastraStorageExporter(), // Studio access
          new LangfuseExporter({
            // Additional destination
            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
            secretKey: process.env.LANGFUSE_SECRET_KEY,
          }),
        ],
      },
    },
  }),
})

OpenTelemetry 设置要求

OtelBridge 需要活动的 OpenTelemetry SDK 才能运行。Bridge 从 OTEL 的环境上下文中读取信息。

完整设置说明（包括如何配置 OTEL 埋点和运行应用）请参阅 OtelBridge 指南。

标签支持

OtelBridge 支持使用 Trace 标签进行分类和筛选。标签仅应用于根 Span，并作为原生 OTEL Span 的 mastra.tags 属性包含在内。

用法

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

标签的存储方式

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

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

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

相关内容

• OtelBridge 指南：包含示例的设置指南
• Tracing 概述：常规 tracing 概念
• OtelExporter 参考：用于发送 Trace 的 OTEL Exporter