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

# OtelBridge

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

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

## 构造函数

```typescript
new OtelBridge()
```

## 方法

### `executeInContext`

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

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

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

### `executeInContextSync`

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

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

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

### `onLogEvent`

```typescript
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`

```typescript
async flush(): Promise<void>
```

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

### `shutdown`

```typescript
async shutdown(): Promise<void>
```

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

## 用法示例

### 基本用法

```typescript
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 将数据发送到其他目标：

```typescript
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 指南](https://mastra.zisheng.pro/docs/observability/integrations/bridges/otel)。

## 标签支持

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

### 用法

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

### 标签的存储方式

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

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

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

## 相关内容

- [OtelBridge 指南](https://mastra.zisheng.pro/docs/observability/integrations/bridges/otel)：包含示例的设置指南
- [Tracing 概述](https://mastra.zisheng.pro/docs/observability/tracing/overview)：常规 tracing 概念
- [OtelExporter 参考](https://mastra.zisheng.pro/reference/observability/tracing/exporters/otel)：用于发送 Trace 的 OTEL Exporter