OtelBridge

警告

OpenTelemetry Bridge は現在実験的です。API と設定オプションは今後のリリースで変更される可能性があります。

Mastra tracing と OpenTelemetry インフラストラクチャの双方向統合を可能にします。Mastra の操作に対してネイティブ OTEL Span を作成し、アクティブな OTEL Span からコンテキストを継承します。また、Mastra のログイベントをグローバル登録された OTEL LoggerProvider に転送し、各ログを発生元の Mastra Span の OTEL コンテキスト下で出力するため、Trace とログが自動的に関連付けられます。

コンストラクター

new OtelBridge()

メソッド

executeInContext

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

Mastra Span の OTEL コンテキスト内で非同期関数を実行します。関数内で実行される OTEL 計装済みコードには、正しい親子関係が設定されます。

戻り値： Promise<T> - 関数の実行結果。

executeInContextSync

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

Mastra Span の OTEL コンテキスト内で同期関数を実行します。

戻り値： T - 関数の実行結果。

onLogEvent

async onLogEvent(event: LogEvent): Promise<void>

Mastra のログイベントをグローバル登録された OTEL LoggerProvider に転送します。Trace の関連付けは次の順序で解決されます。

1. ログが、Bridge に対応する OTEL Span のある spanId を持つ場合、その Span に保存された OTEL コンテキスト下でログを出力します。
2. それ以外で、ログが traceId と spanId を持つ場合、それらの ID を出力するログレコードの SpanContext に付与します。
3. それ以外の場合、現在アクティブな OTEL コンテキスト下でログを出力します。

グローバルに LoggerProvider が登録されていない場合、出力は何もせず正常に終了します。

flush

async flush(): Promise<void>

グローバル OTEL tracer provider と logger provider が forceFlush に対応している場合、強制的にフラッシュします。ランタイムの終了前に 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 コンテキストを処理し、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 のアンビエントコンテキストを読み取ります。

OTEL の計装方法やアプリケーションの実行方法を含む完全なセットアップ手順については、OtelBridge ガイドを参照してください。

タグのサポート

OtelBridge は、分類とフィルタリングのための Trace タグ付けに対応しています。タグはルート Span にのみ適用され、ネイティブ OTEL Span の mastra.tags 属性に含まれます。

使用方法

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 互換バックエンドおよび collector との互換性が確保されます。

関連項目

• OtelBridge ガイド：使用例を含むセットアップガイド
• Tracing の概要：Tracing の一般概念
• OtelExporter リファレンス：Trace を送信するための OTEL exporter