MastraPlatformExporter

追加バージョン： @mastra/observability@1.12.0。以前のリリース（@mastra/observability@1.8.0 から 1.11.x）では、同じ exporter が非推奨の CloudExporter として export されています。

オンラインでの可視化とモニタリングのために、Tracing の Span、ログ、メトリクス、スコア、フィードバックを Mastra platform へ送信します。

注記

MastraPlatformExporter は以前 CloudExporter と呼ばれていました。既存の import が引き続き動作するよう、元の CloudExporter クラスも @mastra/observability から引き続き export されますが、非推奨であり、将来のメジャーバージョンで削除されます。新しいコードでは MastraPlatformExporter を使用してください。

コンストラクター

new MastraPlatformExporter(config?: MastraPlatformExporterConfig)

MastraPlatformExporterConfig

interface MastraPlatformExporterConfig extends BaseExporterConfig {
  /** Maximum number of buffered events per batch (spans, logs, metrics, scores, feedback). Default: 1000 */
  maxBatchSize?: number

  /** Maximum wait time before flushing in milliseconds. Default: 5000 */
  maxBatchWaitMs?: number

  /** Maximum retry attempts. Default: 3 */
  maxRetries?: number

  /** Mastra Observability access token (from env or config) */
  accessToken?: string

  /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */
  projectId?: string

  /** Base observability endpoint */
  endpoint?: string

  /** Explicit traces endpoint override */
  tracesEndpoint?: string

  /** Explicit logs endpoint override */
  logsEndpoint?: string

  /** Explicit metrics endpoint override */
  metricsEndpoint?: string

  /** Explicit scores endpoint override */
  scoresEndpoint?: string

  /** Explicit feedback endpoint override */
  feedbackEndpoint?: string
}

BaseExporterConfig を拡張し、次の項目を含みます。

• logger?: IMastraLogger - Logger インスタンス
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - ログレベル（デフォルト：INFO）

環境変数

config に指定されていない場合、exporter は次の環境変数を読み取ります。

• MASTRA_PLATFORM_ACCESS_TOKEN - MastraPlatformExporter リクエスト用の認証 token
• MASTRA_PROJECT_ID - /projects/:projectId/ai/spans/publish など、プロジェクトスコープの collector route を生成するときに使用するプロジェクト ID
• MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT - Observability エンドポイントの上書き。ベース origin または Trace publish URL 全体を指定します。@mastra/observability@1.9.2 以降のデフォルトは https://observability.mastra.ai です

プロパティ

readonly name = 'mastra-platform-exporter';

後方互換性のため、非推奨の CloudExporter クラスは引き続き 'mastra-cloud-observability-exporter' を name として使用します。

メソッド

exportTracingEvent

async exportTracingEvent(event: TracingEvent): Promise<void>

Mastra platform へエクスポートする Tracing イベントを処理します。

SPAN_ENDED Tracing イベントのみがエクスポートされます。SPAN_STARTED と SPAN_UPDATED は無視されます。一致する Span はバッファーに追加され、次回のフラッシュ時に Trace エンドポイントへアップロードされます。

戻り値： Tracing イベントがバッファーへの追加対象として受け入れられるか、無視された後の Promise<void>。

onLogEvent

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

エクスポートするログシグナルを処理します。

このハンドラーに渡されたすべての LogEvent はバッファーに追加され、設定されたベースエンドポイントから生成されたログエンドポイントへエクスポートされます。Tracing とは異なり、MastraPlatformExporter レベルでイベントステータスによる追加フィルタリングは行われません。exporter が無効な場合、このメソッドは何も行いません。

戻り値： ログイベントがバッファーへの追加対象として受け入れられた後の Promise<void>。

onMetricEvent

async onMetricEvent(event: MetricEvent): Promise<void>

エクスポートするメトリクスシグナルを処理します。

このハンドラーに渡されたすべての MetricEvent はバッファーに追加され、設定されたベースエンドポイントから生成されたメトリクスエンドポイントへエクスポートされます。MastraPlatformExporter 内でメトリクスのサブタイプやステータスによる追加フィルタリングは行われません。exporter は、無効でない限り、受信したすべてのメトリクスイベントを転送します。

戻り値： メトリクスイベントがバッファーへの追加対象として受け入れられた後の Promise<void>。

onScoreEvent

async onScoreEvent(event: ScoreEvent): Promise<void>

エクスポートするスコアシグナルを処理します。

このハンドラーに渡されたすべての ScoreEvent はバッファーに追加され、設定されたベースエンドポイントから生成されたスコアエンドポイントへエクスポートされます。exporter レイヤーでは、exporter が無効かどうかの確認以外に追加フィルタリングは行われないため、このメソッドが受信したすべてのスコアイベントが転送されます。

戻り値： スコアイベントがバッファーへの追加対象として受け入れられた後の Promise<void>。

onFeedbackEvent

async onFeedbackEvent(event: FeedbackEvent): Promise<void>

エクスポートするフィードバックシグナルを処理します。

このハンドラーに渡されたすべての FeedbackEvent はバッファーに追加され、設定されたベースエンドポイントから生成されたフィードバックエンドポイントへエクスポートされます。MastraPlatformExporter 内でフィードバックタイプによるフィルタリングは行われません。exporter が無効でない限り、ここで受信したすべてのフィードバックイベントが転送されます。

戻り値： フィードバックイベントがバッファーへの追加対象として受け入れられた後の Promise<void>。

flush

async flush(): Promise<void>

exporter をシャットダウンせず、バッファー内のすべてのイベントを Mastra platform へ強制的にフラッシュします。ランタイム終了前に Span が確実にエクスポートされるようにする必要があるサーバーレス環境で役立ちます。

shutdown

async shutdown(): Promise<void>

残っているイベントをフラッシュし、クリーンアップを実行します。

動作

認証

config または環境変数から access token が指定されていない場合、exporter は次のように動作します。

• サインアップ情報を含む警告をログに記録します
• 何も行わず動作します（すべてのイベントを破棄します）

バッチ処理

exporter は、ネットワークを効率的に使用するため、Tracing の Span、ログ、メトリクス、スコア、フィードバックをバッチ処理します。

• バッファー内のイベント総数が maxBatchSize に達するとフラッシュします
• バッチ内の最初のシグナルがバッファーに追加されてから maxBatchWaitMs が経過するとフラッシュします
• shutdown() 時にフラッシュします

エラー処理

• maxRetries 回の指数バックオフ再試行を使用します
• すべての再試行に失敗するとバッチを破棄します
• エラーをログに記録しますが、新しいイベントの処理は続行します

MastraPlatformExporter が発生させるエラーは、MASTRA_PLATFORM_EXPORTER_* という id prefix を使用します。非推奨の CloudExporter は引き続き CLOUD_EXPORTER_* id を出力します。

エンドポイントのルーティング

• ベース origin からシグナルエンドポイントを自動生成します
• projectId がない場合、生成される route は /ai/{signal}/publish を使用します
• projectId または MASTRA_PROJECT_ID がある場合、生成される route は /projects/:projectId/ai/{signal}/publish を使用します
• publish URL 全体を明示した場合は、projectId が設定されていてもそのまま使用されます

シグナル処理

• exportTracingEvent() は SPAN_ENDED Tracing イベントのみをエクスポートします
• onLogEvent()、onMetricEvent()、onScoreEvent()、onFeedbackEvent() は、それぞれのシグナルタイプについて受信したすべてのイベントをバッファーに追加します
• サポートされるすべてのシグナルのバッチは、flush() と shutdown() の実行中に対応する publish エンドポイントへアップロードされます

Span の wire format

Mastra platform へ送信される各 Span の形式を、参考として次に示します。これは @mastra/observability から export されないため、import しないでください。exporter は元の AnyExportedSpan を展開し（元のフィールド名を維持します）、その上に platform 向けの少数の alias を追加します。

type MastraPlatformSpanRecord = AnyExportedSpan & {
  // Aliases derived from the source span
  spanId: string // alias for span.id
  spanType: string // alias for span.type
  startedAt: Date // alias for span.startTime
  endedAt: Date | null // alias for span.endTime ?? null
  error: AnyExportedSpan['errorInfo'] | null

  // Stamped at export time
  createdAt: Date
  updatedAt: Date | null
}

展開された AnyExportedSpan には、元の id、type、name、traceId、parentSpanId、isRootSpan、isEvent、startTime、endTime、entityType、entityId、entityName、tags、attributes、metadata、input、output、errorInfo も含まれます。AnyExportedSpan についてはインターフェースを参照してください。

使用方法

import { MastraPlatformExporter } from '@mastra/observability'

// Uses environment variable for token
const exporter = new MastraPlatformExporter()

// Explicit configuration
const customExporter = new MastraPlatformExporter({
  accessToken: 'your-token',
  projectId: 'project_123',
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  logLevel: 'debug',
})

CloudExporter からの移行

両クラスのコンストラクターシグネチャ、環境変数、動作は同じです。移行するには、import とコンストラクターを置き換えます。

// Before
import { CloudExporter } from '@mastra/observability'
const exporter = new CloudExporter()

// After
import { MastraPlatformExporter } from '@mastra/observability'
const exporter = new MastraPlatformExporter()

以前の CLOUD_EXPORTER_* エラー ID または mastra-cloud-observability-exporter exporter 名に一致するダッシュボードやアラートルールが、移行するまで引き続き動作するよう、元の CloudExporter は変更されずに維持されます。

関連項目

ドキュメント

• Tracing の概要：完全なガイド
• Exporter：exporter の概念

その他の Exporter

• MastraStorageExporter：ストレージへの永続化
• ConsoleExporter：デバッグ出力
• Langfuse：Langfuse 連携
• Braintrust：Braintrust 連携

リファレンス

• 設定：設定オプション
• インターフェース：型定義