> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# 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` を使用してください。

## コンストラクター

```typescript
new MastraPlatformExporter(config?: MastraPlatformExporterConfig)
```

## `MastraPlatformExporterConfig`

```typescript
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` です

## プロパティ

```typescript
readonly name = 'mastra-platform-exporter';
```

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

## メソッド

### `exportTracingEvent`

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

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

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

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

### `onLogEvent`

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

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

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

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

### `onMetricEvent`

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

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

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

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

### `onScoreEvent`

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

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

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

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

### `onFeedbackEvent`

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

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

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

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

### flush

```typescript
async flush(): Promise<void>
```

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

### shutdown

```typescript
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 を追加します。

```typescript
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` については[インターフェース](https://mastra.zisheng.pro/ja/reference/observability/tracing/interfaces)を参照してください。

## 使用方法

```typescript
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 とコンストラクターを置き換えます。

```typescript
// 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 の概要](https://mastra.zisheng.pro/ja/docs/observability/tracing/overview)：完全なガイド
- [Exporter](https://mastra.zisheng.pro/ja/docs/observability/integrations/overview)：exporter の概念

### その他の Exporter

- [MastraStorageExporter](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/mastra-storage-exporter)：ストレージへの永続化
- [ConsoleExporter](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/console-exporter)：デバッグ出力
- [Langfuse](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/langfuse)：Langfuse 連携
- [Braintrust](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/braintrust)：Braintrust 連携

### リファレンス

- [設定](https://mastra.zisheng.pro/ja/reference/observability/tracing/configuration)：設定オプション
- [インターフェース](https://mastra.zisheng.pro/ja/reference/observability/tracing/interfaces)：型定義