OpenTelemetry Bridge

警告

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

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

想在沒有現有 OTEL 基礎架構的情況下傳送 Trace？

如果沒有現有的 OpenTelemetry instrumentation，使用 OpenTelemetry Exporter 可能較為簡單。它不需要設定 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

npm install @mastra/otel-bridge

pnpm

pnpm add @mastra/otel-bridge

Yarn

yarn add @mastra/otel-bridge

Bun

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 檔案。此檔案必須先於應用程式程式碼執行：

instrumentation.ts

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 設定：

src/mastra/index.ts

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：

instrumentation.ts

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 先於應用程式載入：

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

語意慣例

OtelBridge 使用 OpenTelemetry Semantic Conventions for GenAI v1.38.0 匯出 Mastra span。其中包括標準化的 span 名稱（chat {model}、execute_tool {tool_name} 等）與 attribute（gen_ai.usage.input_tokens、gen_ai.request.model 等）。

如需 span 命名與 attribute 的詳細資訊，請參閱 OpenTelemetry Exporter 語意慣例。

Trace 階層

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

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 會自動傳播：

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：

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 總覽
• OpenTelemetry Exporter：用於將 Trace 傳送至 OTEL backend
• OtelBridge 參考：API 文件