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

# 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 プロジェクトを作成](https://mastra.zisheng.pro/ja/guides/getting-started/quickstart)します。
> 2. `mastra studio deploy` を使用して、[Studio を Mastra platform へデプロイ](https://mastra.zisheng.pro/ja/docs/studio/deployment)します。
> 3. [以下のクイックスタート手順](#quickstart)に従い、アクセストークンを作成してプロジェクト 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. アクセストークンを作成する

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

```bash
mastra auth tokens create exporter-token
```

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

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

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

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

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
```

### 2. `projectId` を確認する

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

```bash
mastra studio deploy list
```

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

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

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

```text
<your-project-id>
```

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

```bash
MASTRA_PROJECT_ID=<your-project-id>
```

### 3. 環境変数を設定する

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

```bash
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 も明示的に設定します。

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai
```

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

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
```

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

### 4. `MastraPlatformExporter` を有効にする

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

```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 リファレンス](https://mastra.zisheng.pro/ja/reference/observability/tracing/configuration)を参照してください。

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

```ts
new MastraPlatformExporter()
```

`MASTRA_PLATFORM_ACCESS_TOKEN` と `MASTRA_PROJECT_ID` を設定すると、`MastraPlatformExporter` は設定した Mastra platform プロジェクトへデータを送信します。`MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` も設定した場合は、代わりにその collector へデータを送信します。設定オプションの全一覧については、[MastraPlatformExporter リファレンス](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/mastra-platform-exporter)を参照してください。

## 推奨設定

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

```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` を渡します。

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
```

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

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

## Mastra Studio でデータを表示する

`MastraPlatformExporter` を有効にしたら、[Mastra Studio](https://projects.mastra.ai) でプロジェクトを開き、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 は機能を段階的に縮退します。

## 関連情報

- [トレースの概要](https://mastra.zisheng.pro/ja/docs/observability/tracing/overview)
- [MastraStorageExporter](https://mastra.zisheng.pro/ja/docs/observability/integrations/exporters/mastra-storage)