Mastra platform exporter

MastraPlatformExporter は、トレース、ログ、メトリクス、スコア、フィードバックを Mastra platform へ送信します。あらゆる Mastra アプリから、Mastra platform でホストされているプロジェクトへ可観測性データを振り分けるために使用します。

注記

MastraPlatformExporter は以前 CloudExporter という名前でした。元の CloudExporter class は後方互換性のため、引き続き @mastra/observability から export されていますが、非推奨です。新しいコードでは MastraPlatformExporter を使用してください。

セルフホストまたはスタンドアロンのアプリ

Mastra アプリケーションを独自のインフラストラクチャ（Mastra platform 以外）でホストしている場合も、トレース、ログ、メトリクスを表示するには、デプロイ済みの Studio プロジェクトが必要です。MastraPlatformExporter は Studio プロジェクトへデータを送信するため、使用前にプロジェクトを用意する必要があります。

1. まだプロジェクトがない場合は、Mastra プロジェクトを作成します。
2. mastra studio deploy を使用して、Studio を Mastra platform へデプロイします。
3. 以下のクイックスタート手順に従い、アクセストークンを作成してプロジェクト ID を確認します。

バージョンの互換性

• MastraPlatformExporter は @mastra/observability@1.12.0 以降で使用できます。1.8.0 から 1.11.x までは、同じ exporter が CloudExporter としてのみ含まれています。constructor のシグネチャと環境変数は同一です。
• @mastra/observability@1.8.0 から 1.9.1 までは、MASTRA_PLATFORM_ACCESS_TOKEN と MASTRA_PROJECT_ID に加えて、MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai を設定します。
• @mastra/observability@1.9.2 以降、exporter のデフォルトは https://observability.mastra.ai です。そのため、MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT が必要なのは、telemetry を別の collector へ送信する場合のみです。

クイックスタート

MastraPlatformExporter を接続するには、アクセストークンを作成し、送信先の projectId を確認して、可観測性設定に exporter を追加します。

1. アクセストークンを作成する

次のコマンドを実行します。

mastra auth tokens create exporter-token

このコマンドは、MASTRA_PLATFORM_ACCESS_TOKEN として使用できる token secret を出力します。

すでにアクセストークンがある場合は、代わりに Mastra platform から Observability の値をコピーします。この値は、次のいずれかの場所にあります。

• Projects ページでプロジェクトリストを開き、プロジェクトカードの Observability 行を確認します。
• プロジェクトの Overview ページで、デプロイ URL の直下にある Observability 行を確認します。

トークンを環境変数として設定します。

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>

2. projectId を確認する

次のコマンドを実行します。

mastra studio deploy list

出力は次のようになります。

✅ <your-project-name> (<your-project-id>)
   Latest:   00000000-0000-0000-0000-000000000000 — running
   URL:      https://260407.studio.mastra.cloud

この出力では、括弧内の値が projectId です。

<your-project-id>

環境変数として設定します。

.env

MASTRA_PROJECT_ID=<your-project-id>

3. 環境変数を設定する

MastraPlatformExporter が認証を行い、telemetry を正しいプロジェクトへ振り分けられるよう、両方の値を環境に設定します。

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
MASTRA_PROJECT_ID=<your-project-id>

@mastra/observability@1.8.0 から 1.9.1 までを使用している場合は、Mastra platform の collector も明示的に設定します。

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai

telemetry を Mastra platform 以外へ送信する場合も、MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT を設定します。base origin、または /spans/publish で終わる完全なトレース公開 URL のいずれかを指定してください。

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

base origin を指定すると、MastraPlatformExporter はトレース、ログ、メトリクス、スコア、フィードバックに対応する公開 URL を自動的に生成します。

4. MastraPlatformExporter を有効にする

次の例は、可観測性設定に MastraPlatformExporter を追加する方法を示しています。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraPlatformExporter } from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'api-server',
        exporters: [new MastraPlatformExporter()],
      },
    },
  }),
})

serviceName は MastraPlatformExporter 自体ではなく、可観測性設定に指定します。

安定した serviceName 値を使用してください。Studio では Deployments → Service Name でトレースをフィルタリングできるため、一貫した名前を使用するとトレースを見つけやすくなります。

可観測性設定の完全な形式については、Observability configuration リファレンスを参照してください。

必要に応じて、環境変数だけに依存することもできます。

src/mastra/index.ts

new MastraPlatformExporter()

MASTRA_PLATFORM_ACCESS_TOKEN と MASTRA_PROJECT_ID を設定すると、MastraPlatformExporter は設定した Mastra platform プロジェクトへデータを送信します。MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT も設定した場合は、代わりにその collector へデータを送信します。設定オプションの全一覧については、MastraPlatformExporter リファレンスを参照してください。

推奨設定

Studio でローカルトレースも確認したい場合や、設定済みの storage に可観測性データを永続化したい場合は、MastraStorageExporter も含めます。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

完全な設定

MastraPlatformExporter のデフォルトの送信先は Mastra platform です。telemetry を別の collector へ送信するには、環境で MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT を設定するか、コードで endpoint を渡します。

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

次の例は、コードで collector endpoint とバッチ処理の動作を上書きする方法を示しています。

src/mastra/index.ts

new MastraPlatformExporter({
  endpoint: 'https://collector.example.com',
  maxBatchSize: 1000,
  maxBatchWaitMs: 5000,
  logLevel: 'info',
})

Mastra Studio でデータを表示する

MastraPlatformExporter を有効にしたら、Mastra Studio でプロジェクトを開き、export されたデータを確認します。

• MASTRA_PROJECT_ID に設定したプロジェクトを開き、Open Studio を選択します。
• Studio で Traces を開き、Agent と Workflow のトレースを確認します。
• フィルターメニューを開き、Deployments → Service Name を使用して、特定のアプリまたはデプロイのトレースだけを表示します。
• プロジェクト dashboard の Logs ページで、export されたログを確認します。

Mastra Studio でデプロイする際は、Deployment → Service Name に安定した値を設定し、可観測性設定の serviceName と一致させます。複数のサービスやデプロイが同じプロジェクトへデータを送信する場合も、Studio の Deployments → Service Name でトレースをフィルタリングしやすくなります。

パフォーマンス

情報

MastraPlatformExporter は、ネットワーク使用量を最適化するためにバッチ処理を使用します。イベントはバッファリングされてバッチ単位で送信されるため、ほぼリアルタイムの可視性を維持しながらオーバーヘッドを削減できます。

バッチ処理の動作

• イベントは maxBatchSize（デフォルト: 1000）までバッチ化されます。
• バッチが上限に達したとき、または maxBatchWaitMs（デフォルト: 5 秒）の経過後に送信されます。
• 失敗したバッチは exponential backoff で再試行されます。
• Mastra Studio に接続できない場合、exporter は機能を段階的に縮退します。

関連情報

• トレースの概要
• MastraStorageExporter