OtelBridge

警告

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

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

建構函式

new OtelBridge()

方法

executeInContext

executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>

在 Mastra span 的 OTEL context 中執行非同步函式。在此函式內執行且已進行 OTEL 檢測的程式碼，會具有正確的父層關係。

傳回：Promise<T> - 函式執行結果。

executeInContextSync

executeInContextSync<T>(spanId: string, fn: () => T): T

在 Mastra span 的 OTEL context 中執行同步函式。

傳回：T - 函式執行結果。

onLogEvent

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

async flush(): Promise<void>

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

shutdown

async shutdown(): Promise<void>

關閉 bridge 並清理資源。結束所有未正確關閉的 span。

使用範例

基本使用方式

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 則將資料傳送至其他目的地：

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 指南。

標籤支援

OtelBridge 支援以 trace 標籤進行分類與篩選。標籤只會套用至根 span，並以原生 OTEL span 的 mastra.tags 屬性納入。

使用方式

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

標籤的儲存方式

標籤會以 JSON 字串化 array 的形式，儲存於 mastra.tags span 屬性中：

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

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

相關內容

• OtelBridge 指南：含範例的設定指南
• Tracing 概覽：一般 tracing 概念
• OtelExporter 參考：用於傳送 trace 的 OTEL exporter