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

# OtelBridge

> **注意:** OpenTelemetry Bridge 目前仍屬**實驗性質**。API 及設定選項可能會在日後版本中變更。

在 Mastra tracing 與 OpenTelemetry 基礎設施之間提供雙向整合。它會為 Mastra 操作建立原生 OTEL span，並繼承現用 OTEL span 的 context。此外，它亦會將 Mastra 日誌事件轉送至全域註冊的 OTEL `LoggerProvider`，並在來源 Mastra span 的 OTEL context 下發出每項日誌，讓 Trace 與日誌自動建立關聯。

## 建構函式

```typescript
new OtelBridge()
```

## 方法

### `executeInContext`

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

在 Mastra span 的 OTEL context 中執行非同步函式。函式內執行並已由 OTEL 檢測的程式碼，將具有正確的父項關係。

**傳回：** `Promise<T>` - 函式的執行結果。

### `executeInContextSync`

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

在 Mastra span 的 OTEL context 中執行同步函式。

**傳回：** `T` - 函式的執行結果。

### `onLogEvent`

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

將 Mastra 日誌事件轉送至全域註冊的 OTEL `LoggerProvider`。Trace 關聯會按以下順序判定：

1. 如果日誌帶有 `spanId`，而 bridge 已為其建立 OTEL span，則會在該 span 已儲存的 OTEL context 下發出日誌。
2. 否則，如果日誌帶有 `traceId` 及 `spanId`，這些 ID 會附加至所發出日誌記錄的 `SpanContext`。
3. 否則，日誌會在目前現用的 OTEL context 下發出。

如果未有全域註冊的 `LoggerProvider`，發出操作會靜默略過，不會產生任何效果。

### `flush`

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

如果全域 OTEL tracer provider 及 logger provider 支援 `forceFlush`，便會強制清空兩者。這適用於無伺服器環境，讓你可在 runtime 終止前送出所有遙測資料。

### `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 context，而 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 的環境 context 讀取資料。

如需完整設定指引，包括如何設定 OTEL instrumentation 及執行應用程式，請參閱 [OtelBridge 指南](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/bridges/otel)。

## 標籤支援

OtelBridge 支援以 Trace 標籤進行分類及篩選。標籤只會套用至根 span，並以 `mastra.tags` 屬性的形式加入原生 OTEL span。

### 用法

```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/zh-HK/docs/observability/integrations/bridges/otel)：附有範例的設定指南
- [Tracing 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)：一般 tracing 概念
- [OtelExporter 參考](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/otel)：用於傳送 Trace 的 OTEL exporter