OpenTelemetry bridge

注意

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

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

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

如果你沒有現有的 OpenTelemetry instrumentation，OpenTelemetry Exporter 可能更簡單；它無需設定 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

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 - 常用函式庫的 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 檔案。此檔案必須在你的應用程式程式碼之前執行：

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 config：

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

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

相關內容

• Tracing 概覽
• OpenTelemetry Exporter：用於將 trace 傳送至 OTEL backend
• OtelBridge 參考：API 文檔