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

# OpenTelemetry bridge

> **注意:** OpenTelemetry Bridge 目前仍屬**實驗性質**。API 和配置選項可能會在未來版本中變更。

OpenTelemetry (OTEL) Bridge 讓 Mastra 的 tracing 系統與現有 OpenTelemetry 基礎架構進行雙向整合。與將 trace 數據傳送至外部平台的 exporter 不同，bridge 會建立原生 OTEL span，並加入你的分散式 tracing context。

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

## 何時使用 bridge

如有以下需要，請使用 OtelBridge：

- 應用程式中已有 OTEL instrumentation（HTTP 伺服器、數據庫 client 等）
- 希望 Mastra 操作在現有 OTEL trace 中顯示為 child span
- 需要 Mastra Tool 內已使用 OTEL instrumentation 的程式碼維持正確的 parent-child 關係
- 正在建構必須跨服務傳播 trace context 的分散式系統

## 運作方式

OtelBridge 提供雙向整合：

**從 OTEL 到 Mastra：**

- 自動從 OTEL ambient context (AsyncLocalStorage) 讀取資料
- 從目前使用中的 OTEL span 繼承 trace ID 和 parent span ID
- 遵從 OTEL sampling 決定：如果 trace 未被採樣，Mastra 便不會為其建立 span
- 啟用 OTEL auto-instrumentation 時，無需手動傳遞 trace ID

**從 Mastra 到 OTEL：**

- 為 Mastra 操作（Agent、LLM call、Tool、Workflow）建立原生 OTEL span
- 在分散式 trace 中維持正確的 parent-child 關係
- 讓 Mastra 操作內已使用 OTEL instrumentation 的程式碼（HTTP client、數據庫 call）正確建立巢狀結構
- 將 Mastra log event 轉發至全域註冊的 OTEL `LoggerProvider`。源自 Mastra span 內的 log 會在該 span 的 OTEL context 下發出，讓 backend 可將它們與 trace 建立關聯。如果沒有註冊 `LoggerProvider`，發出 log 時會靜默地不執行任何操作。

## 安裝

**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` - 常用函式庫的 auto-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` - 核心 utility（用於 W3CTraceContextPropagator 等）
- `@opentelemetry/sdk-logs` 及 OTLP log exporter（例如 `@opentelemetry/exporter-logs-otlp-http`）- 如你亦希望 bridge 轉發 Mastra log event，便必須安裝

## 配置

使用 OtelBridge 需要兩個步驟：

1. 在你的應用程式中配置 OpenTelemetry instrumentation
2. 將 OtelBridge 加入 Mastra observability config

### 步驟 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 config：

```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，請將 `logRecordProcessor` 註冊至 `NodeSDK`：

```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 時會靜默地不執行任何操作，而 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-HK/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 call 服務 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，或在 entry point 頂部匯入）
- 確保已將 OtelBridge 加入你的 observability config
- 檢查你的 OTEL backend 正在運行且可供存取

## 相關內容

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