CloudExporter

追加バージョン： @mastra/observability@1.8.0。MastraPlatformExporter の導入に伴い、1.12.0 で非推奨になりました。

非推奨

CloudExporter は後方互換性のために維持されていますが、将来のメジャーバージョンで削除される予定です。新しいプロジェクトでは MastraPlatformExporter を使用してください。両クラスのコンストラクター、環境変数、実行時の動作は同じです。CloudExporter では、既存の監視ルールが引き続き機能するよう、元の exporter name である mastra-cloud-observability-exporter と CLOUD_EXPORTER_* エラー ID が維持されます。

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

コンストラクター

new CloudExporter(config?: CloudExporterConfig)

CloudExporterConfig

interface CloudExporterConfig extends BaseExporterConfig {
  /** Maximum number of spans per batch. Default: 1000 */
  maxBatchSize?: number

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

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

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

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

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

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

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

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

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

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

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

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

環境変数

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

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

プロパティ

readonly name = 'mastra-cloud-observability-exporter';

メソッド

exportTracingEvent

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

Cloud へのエクスポート用に Tracing イベントを処理します。

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

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

onLogEvent

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

Cloud へのエクスポート用にログシグナルを処理します。

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

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

onMetricEvent

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

Cloud へのエクスポート用にメトリクスシグナルを処理します。

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

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

onScoreEvent

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

Cloud へのエクスポート用にスコアシグナルを処理します。

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

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

onFeedbackEvent

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

Cloud へのエクスポート用にフィードバックシグナルを処理します。

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

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

flush

async flush(): Promise<void>

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

shutdown

async shutdown(): Promise<void>

残りのイベントをフラッシュし、クリーンアップを実行します。

動作

認証

設定または環境変数でアクセストークンが指定されていない場合、exporter は次のように動作します。

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

バッチ処理

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

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

エラー処理

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

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

• ベースオリジンからシグナルのエンドポイントを自動的に生成します
• projectId がない場合、生成されるルートには /ai/{signal}/publish を使用します
• projectId または MASTRA_PROJECT_ID がある場合、生成されるルートには /projects/:projectId/ai/{signal}/publish を使用します
• 完全な公開 URL が明示的に指定されている場合、projectId の設定に関係なくそのまま使用します

シグナル処理

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

MastraCloudSpanRecord

Cloud の Span に使用される内部形式です。

interface MastraCloudSpanRecord {
  traceId: string
  spanId: string
  parentSpanId: string | null
  name: string
  spanType: string
  attributes: Record<string, any> | null
  metadata: Record<string, any> | null
  startedAt: Date
  endedAt: Date | null
  input: any
  output: any
  error: any
  isEvent: boolean
  createdAt: Date
  updatedAt: Date | null
}

使用方法

import { CloudExporter } from '@mastra/observability'

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

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

関連項目

ドキュメント

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

その他の Exporter

• DefaultExporter：ストレージへの永続化
• ConsoleExporter：デバッグ出力
• Langfuse：Langfuse との統合
• Braintrust：Braintrust との統合

リファレンス

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