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

# OtelBridge

> **警告:** OpenTelemetry Bridge 目前仍是**實驗性功能**。API 與設定選項可能在未來版本中變更。

在 Mastra tracing 與 OpenTelemetry 基礎架構之間啟用雙向整合。為 Mastra 操作建立原生 OTEL span，並繼承作用中 OTEL span 的 context。此外，也會將 Mastra log 事件轉送至全域註冊的 OTEL `LoggerProvider`；每筆 log 都會在來源 Mastra span 的 OTEL context 下產生，因此 trace 與 log 會自動建立關聯。

## 建構函式

```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 log 事件轉送至全域註冊的 OTEL `LoggerProvider`。Trace 關聯會依下列順序解析：

1. 如果 log 帶有 bridge 對應到 OTEL span 的 `spanId`，則會在該 span 儲存的 OTEL context 下產生 log。
2. 否則，如果 log 帶有 `traceId` 與 `spanId`，這些 ID 會附加至所產生 log record 的 `SpanContext`。
3. 否則，會在目前作用中的 OTEL context 下產生 log。

若未全域註冊 `LoggerProvider`，產生操作會是無聲的 no-op。

### `flush`

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

若全域 OTEL tracer provider 與 logger provider 支援 `forceFlush`，則強制將其 flush。這在 serverless 環境中特別實用，可在 runtime 結束前清空 telemetry。

### `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 的 ambient context 讀取資料。

如需完整設定說明，包括如何設定 OTEL 檢測並執行應用程式，請參閱 [OtelBridge 指南](https://mastra.zisheng.pro/zh-TW/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 字串化 array 的形式，儲存於 `mastra.tags` span 屬性中：

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

此格式可確保與所有 OTEL 相容的後端及 collector 相容。

## 相關內容

- [OtelBridge 指南](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/bridges/otel)：含範例的設定指南
- [Tracing 概覽](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)：一般 tracing 概念
- [OtelExporter 參考](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/otel)：用於傳送 trace 的 OTEL exporter