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

# OpenTelemetry Bridge

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

OpenTelemetry（OTEL）Bridge 能在 Mastra Tracing 系統與現有 OpenTelemetry 基礎架構之間進行雙向整合。Exporter 會將 Trace 資料傳送至外部平台，而 Bridge 則會建立參與分散式 Tracing context 的原生 OTEL span。

> **想在沒有現有 OTEL 基礎架構的情況下傳送 Trace？:** 如果沒有現有的 OpenTelemetry instrumentation，使用 [OpenTelemetry Exporter](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/otel) 可能較為簡單。它不需要設定 OTEL SDK，即可直接傳送 Trace。

## 使用 Bridge 的時機

下列情況適合使用 OtelBridge：

- 應用程式已有 OTEL instrumentation（HTTP Server、資料庫 Client 等）
- 希望 Mastra 作業顯示為現有 OTEL Trace 的子 span
- 需要 Mastra Tool 內已進行 OTEL instrumentation 的程式碼維持正確的父子關係
- 正在建立需要跨服務傳播 Trace context 的分散式系統

## 運作方式

OtelBridge 提供雙向整合：

**從 OTEL 至 Mastra：**

- 自動從 OTEL ambient context（AsyncLocalStorage）讀取
- 從啟用中的 OTEL span 繼承 Trace ID 與父 span ID
- 遵循 OTEL 取樣決策：若 Trace 未被取樣，Mastra 不會為其建立 span
- 啟用 OTEL 自動 instrumentation 時，不需要手動傳遞 Trace ID

**從 Mastra 至 OTEL：**

- 為 Mastra 作業（Agent、LLM 呼叫、Tool、Workflow）建立原生 OTEL span
- 在分散式 Trace 中維持正確的父子關係
- 讓 Mastra 作業內已進行 OTEL instrumentation 的程式碼（HTTP Client、資料庫呼叫）正確巢狀排列
- 將 Mastra Log event 轉送至全域註冊的 OTEL `LoggerProvider`。源自 Mastra span 內部的 Log 會在該 span 的 OTEL context 下發送，讓 backend 能將其與 Trace 建立關聯。若未註冊 `LoggerProvider`，發送 Log 會是無聲的 no-op。

## 安裝

**npm**:

```bash
npm install @mastra/otel-bridge
```

**pnpm**:

```bash
pnpm add @mastra/otel-bridge
```

**Yarn**:

```bash
yarn add @mastra/otel-bridge
```

**Bun**:

```bash
bun add @mastra/otel-bridge
```

Bridge 可搭配現有的 OpenTelemetry 設定運作。依據你的設定，可能還需要下列部分套件：

- `@opentelemetry/sdk-node`－OTEL 的核心 Node.js SDK
- `@opentelemetry/auto-instrumentations-node`－常用 library 的自動 instrumentation
- `@opentelemetry/exporter-trace-otlp-proto`－OTLP Exporter（透過 HTTP 傳輸 Protobuf）
- `@opentelemetry/exporter-trace-otlp-http`－OTLP Exporter（透過 HTTP 傳輸 JSON）
- `@opentelemetry/exporter-trace-otlp-grpc`－OTLP Exporter（gRPC）
- `@opentelemetry/sdk-trace-base`－基礎 Tracing SDK（適用於 BatchSpanProcessor 等）
- `@opentelemetry/core`－核心公用程式（適用於 W3CTraceContextPropagator 等）
- `@opentelemetry/sdk-logs` 與 OTLP Log Exporter（例如 `@opentelemetry/exporter-logs-otlp-http`）－如果也要讓 Bridge 轉送 Mastra Log event，則為必要套件

## 設定

使用 OtelBridge 需要完成兩個步驟：

1. 在應用程式中設定 OpenTelemetry instrumentation
2. 將 OtelBridge 加入 Mastra Observability 設定

### 步驟 1：OpenTelemetry instrumentation

建立會初始化 OTEL 的 instrumentation 檔案。此檔案必須先於應用程式程式碼執行：

```typescript
import { NodeSDK } from '@opentelemetry/sdk-node'
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
import { W3CTraceContextPropagator } from '@opentelemetry/core'

const sdk = new NodeSDK({
  serviceName: 'my-service',
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({
        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
      }),
    ),
  ],
  instrumentations: [getNodeAutoInstrumentations()],
  textMapPropagator: new W3CTraceContextPropagator(),
})

sdk.start()

export { sdk }
```

### 步驟 2：設定 Mastra

將 OtelBridge 加入 Mastra Observability 設定：

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelBridge } from '@mastra/otel-bridge'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        bridge: new OtelBridge(),
      },
    },
  }),
  agents: {/* your agents */},
})
```

使用 Bridge 時不需要 Mastra Exporter，Trace 會透過 OTEL SDK 設定傳送。如果要將 Trace 傳送至其他目的地，也可以選擇加入 Mastra Exporter。

### 轉送 Log（選用）

Bridge 也會將 Mastra Log event 轉送至全域註冊的 OTEL `LoggerProvider`。若要同時連接 Log 與 Trace，請在 `NodeSDK` 上註冊 `logRecordProcessor`：

```typescript
import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs'

const sdk = new NodeSDK({
  // ...trace config as usual
  logRecordProcessor: new BatchLogRecordProcessor(
    new OTLPLogExporter({
      url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT || 'http://localhost:4318/v1/logs',
    }),
  ),
})
```

源自 Mastra span 內部的 Log 會在該 span 的 OTEL context 下發送，因此 Datadog、Grafana 與 Honeycomb 等 backend 會自動將其與周圍的 Trace 建立關聯。沒有 Trace context 的 Log 會使用目前啟用中的 OTEL context。

如果沒有註冊 `LoggerProvider`，發送 Log 會是無聲的 no-op，而 Trace 會繼續依設定運作。

### 執行應用程式

使用 `--import` flag，確保 instrumentation 先於應用程式載入：

```bash
tsx --import ./instrumentation.ts ./src/index.ts
```

## 語意慣例

OtelBridge 使用 [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai) 匯出 Mastra span。其中包括標準化的 span 名稱（`chat {model}`、`execute_tool {tool_name}` 等）與 attribute（`gen_ai.usage.input_tokens`、`gen_ai.request.model` 等）。

如需 span 命名與 attribute 的詳細資訊，請參閱 [OpenTelemetry Exporter 語意慣例](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/otel)。

## Trace 階層

使用 OtelBridge 後，Trace 會跨越 OTEL 與 Mastra 邊界維持正確階層：

```text
HTTP POST /api/chat (from Hono middleware)
└── agent.assistant (from Mastra via OtelBridge)
    ├── chat gpt-5.4 (LLM call)
    ├── tool.execute search (tool execution)
    │   └── HTTP GET api.example.com (from OTEL auto-instrumentation)
    └── chat gpt-5.4 (follow-up LLM call)
```

## 多服務分散式 Tracing

OtelBridge 可跨服務邊界傳播 Trace。服務 A 透過 HTTP 呼叫服務 B 時，Trace context 會自動傳播：

```text
Service A: HTTP POST /api/process
└── HTTP POST service-b/api/analyze (outgoing call)

Service B: HTTP POST /api/analyze (incoming call - same trace!)
└── agent.analyzer (Mastra agent inherits trace context)
    └── chat gpt-5.4
```

兩個服務都必須具備：

1. 已設定 OTEL instrumentation
2. 已啟用 W3C Trace Context propagator
3. 已設定 OtelBridge 的 Mastra

## 使用 tag

Tag 可協助你在 OTEL backend 中分類及篩選 Trace。執行 Agent 或 Workflow 時可加入 tag：

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

Tag 會以 JSON 字串形式匯出至 `mastra.tags` span attribute，以提供廣泛的 backend 相容性。常見使用情境包括：

- 環境 label：`"production"`、`"staging"`
- 實驗追蹤：`"experiment-v1"`、`"control-group"`
- 優先層級：`"priority-high"`、`"batch-job"`

## 疑難排解

如果 Trace 未如預期顯示或連接：

- 確認 OTEL SDK 先於 Mastra 初始化（使用 `--import` flag，或在進入點頂端匯入）
- 確認已將 OtelBridge 加入 Observability 設定
- 檢查 OTEL backend 是否正在執行且可連線

## 相關內容

- [Tracing 總覽](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)
- [OpenTelemetry Exporter](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/otel)：用於將 Trace 傳送至 OTEL backend
- [OtelBridge 參考](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/bridges/otel)：API 文件