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

# CloudExporter

**追加バージョン：** `@mastra/observability@1.8.0`。[`MastraPlatformExporter`](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/mastra-platform-exporter) の導入に伴い、**`1.12.0` で非推奨になりました**。

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

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

## コンストラクター

```typescript
new CloudExporter(config?: CloudExporterConfig)
```

## `CloudExporterConfig`

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

## プロパティ

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

## メソッド

### `exportTracingEvent`

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

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

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

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

### `onLogEvent`

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

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

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

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

### `onMetricEvent`

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

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

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

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

### `onScoreEvent`

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

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

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

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

### `onFeedbackEvent`

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

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

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

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

### flush

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

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

### shutdown

```typescript
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 に使用される内部形式です。

```typescript
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
}
```

## 使用方法

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

### その他の Exporter

- [DefaultExporter](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/default-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)：型定義