OtelBridge

注意

OpenTelemetry Bridge 目前仍屬實驗性質。API 及設定選項可能會在日後版本中變更。

在 Mastra tracing 與 OpenTelemetry 基礎設施之間提供雙向整合。它會為 Mastra 操作建立原生 OTEL span，並繼承現用 OTEL span 的 context。此外，它亦會將 Mastra 日誌事件轉送至全域註冊的 OTEL LoggerProvider，並在來源 Mastra span 的 OTEL context 下發出每項日誌，讓 Trace 與日誌自動建立關聯。

建構函式

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 日誌事件轉送至全域註冊的 OTEL LoggerProvider。Trace 關聯會按以下順序判定：

1. 如果日誌帶有 spanId，而 bridge 已為其建立 OTEL span，則會在該 span 已儲存的 OTEL context 下發出日誌。
2. 否則，如果日誌帶有 traceId 及 spanId，這些 ID 會附加至所發出日誌記錄的 SpanContext。
3. 否則，日誌會在目前現用的 OTEL context 下發出。

如果未有全域註冊的 LoggerProvider，發出操作會靜默略過，不會產生任何效果。

flush

async flush(): Promise<void>

如果全域 OTEL tracer provider 及 logger provider 支援 forceFlush，便會強制清空兩者。這適用於無伺服器環境，讓你可在 runtime 終止前送出所有遙測資料。

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 的環境 context 讀取資料。

如需完整設定指引，包括如何設定 OTEL instrumentation 及執行應用程式，請參閱 OtelBridge 指南。

標籤支援

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

用法

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

標籤的儲存方式

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

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

此格式可確保與所有兼容 OTEL 的後端及收集器配合使用。

相關內容

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