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

# Mastra Storage exporter

`MastraStorageExporter` は、設定済みのストレージバックエンドに Trace を永続化し、Studio からアクセスできるようにします。外部サービスは必要ありません。

> **注記:** `MastraStorageExporter` は以前 `DefaultExporter` という名前でした。元の `DefaultExporter` クラスも後方互換性のために `@mastra/observability` から引き続き export されていますが、非推奨です。新しいコードでは `MastraStorageExporter` を使用してください。

> **本番環境の Observability:** 本番環境では、Observability データによって汎用データベースの処理能力がすぐに圧迫される可能性があります。トラフィック量の多いアプリケーションでは、Observability ストレージドメインを [ClickHouse](https://mastra.zisheng.pro/ja/reference/storage/clickhouse) へ、[composite storage](https://mastra.zisheng.pro/ja/reference/storage/composite) を介してルーティングしてください。詳細は[本番環境での推奨事項](#production-recommendations)を参照してください。

## 設定

### 前提条件

1. **ストレージバックエンド**：ストレージ Provider（libSQL、PostgreSQL など）を設定します
2. **Studio**：Trace をローカルで表示するためにインストールします

### 基本設定

```typescript
import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db', // Required for trace persistence
  }),
  observability: new Observability({
    configs: {
      local: {
        serviceName: 'my-service',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})
```

### 推奨設定

Observability の設定に MastraStorageExporter を含めます。

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

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (requires MASTRA_PLATFORM_ACCESS_TOKEN)
        ],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})
```

## Studio

Studio から Trace にアクセスします。

1. Studio を起動します
2. Observability に移動します
3. ローカルの Trace を絞り込み、検索します
4. Span の詳細情報を確認します

## Tracing 戦略

MastraStorageExporter は、ストレージ Provider に基づいて最適な Tracing 戦略を自動的に選択します。必要に応じて、この選択を上書きすることもできます。

### 利用可能な戦略

| 戦略                     | 説明                                       | ユースケース          |
| ---------------------- | ---------------------------------------- | --------------- |
| **realtime**           | 各イベントを即座に処理します                           | 開発、デバッグ、低トラフィック |
| **batch-with-updates** | イベントをバッファーし、ライフサイクル全体をサポートしたバッチ書き込みを行います | 低ボリュームの本番環境     |
| **insert-only**        | 完了した Span のみを処理し、更新を無視します                | 高ボリュームの本番環境     |

### 戦略の設定

```typescript
new MastraStorageExporter({
  strategy: 'auto', // Default - let storage provider decide
  // or explicitly set:
  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only'

  // Batching configuration (applies to both batch-with-updates and insert-only)
  maxBatchSize: 1000, // Max spans per batch
  maxBatchWaitMs: 5000, // Max wait before flushing
  maxBufferSize: 10000, // Max spans to buffer
})
```

## ストレージ Provider のサポート

ストレージ Provider ごとに、サポートする Tracing 戦略が異なります。本番ワークロードの Observability をサポートする Provider もあれば、主にローカル開発を目的とする Provider もあります。

戦略を `'auto'` に設定すると、`MastraStorageExporter` はストレージ Provider に最適な戦略を自動的に選択します。ストレージ Provider がサポートしていない戦略を明示的に設定すると、exporter は警告をログへ記録し、その Provider が推奨する戦略へフォールバックします。

### Observability をサポートする Provider

| ストレージ Provider                                                               | 推奨戦略               | サポートされる戦略                       | 推奨用途                  |
| ---------------------------------------------------------------------------- | ------------------ | ------------------------------- | --------------------- |
| **[ClickHouse](https://mastra.zisheng.pro/ja/reference/storage/clickhouse)** | insert-only        | insert-only                     | 本番環境（高ボリューム）          |
| **[PostgreSQL](https://mastra.zisheng.pro/ja/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | 本番環境（低ボリューム）          |
| **[MSSQL](https://mastra.zisheng.pro/ja/reference/storage/mssql)**           | batch-with-updates | batch-with-updates, insert-only | 本番環境（低ボリューム）          |
| **[MongoDB](https://mastra.zisheng.pro/ja/reference/storage/mongodb)**       | batch-with-updates | batch-with-updates, insert-only | 本番環境（低ボリューム）          |
| **[OracleDB](https://mastra.zisheng.pro/ja/reference/storage/oracledb)**     | batch-with-updates | batch-with-updates, insert-only | 本番環境（低ボリューム）          |
| **[libSQL](https://mastra.zisheng.pro/ja/reference/storage/libsql)**         | batch-with-updates | batch-with-updates, insert-only | デフォルトのストレージ、開発に適しています |

### Observability をサポートしない Provider

次のストレージ Provider は Observability ドメインを**サポートしていません**。これらの Provider を使用していて Observability が必要な場合は、[composite storage](https://mastra.zisheng.pro/ja/reference/storage/composite) を使用して Observability データをサポート対象の Provider へルーティングしてください。

- [Convex](https://mastra.zisheng.pro/ja/reference/storage/convex)
- [DynamoDB](https://mastra.zisheng.pro/ja/reference/storage/dynamodb)
- [Cloudflare D1](https://mastra.zisheng.pro/ja/reference/storage/cloudflare-d1)
- [Cloudflare Durable Objects](https://mastra.zisheng.pro/ja/reference/storage/cloudflare)
- [Upstash](https://mastra.zisheng.pro/ja/reference/storage/upstash)
- [LanceDB](https://mastra.zisheng.pro/ja/reference/storage/lance)

### 各戦略の利点

- **realtime**：即座に表示でき、デバッグに最適です
- **batch-with-updates**：スループットが10～100倍向上し、Span のライフサイクル全体を扱えます
- **insert-only**：データベース操作をさらに70%削減でき、分析に最適です

## 本番環境での推奨事項

本番環境では Observability データが急速に増加します。1回の Agent インタラクションで数百個の Span が生成されることがあり、トラフィック量の多いアプリケーションでは1日に数千件の Trace が生成される可能性があります。ほとんどの汎用データベースは、書き込み量が多い追記専用のワークロード向けに最適化されていません。

### 推奨：高ボリュームの本番環境には ClickHouse

[ClickHouse](https://mastra.zisheng.pro/ja/reference/storage/clickhouse) は、高ボリュームの分析ワークロード向けに設計されたカラム指向データベースです。次の理由から、本番環境の Observability に推奨されます。

- **書き込みに最適化**：毎秒数百万件の insert を処理します
- **効率的な圧縮**：Trace データのストレージコストを削減します
- **高速なクエリ**：カラム指向ストレージにより、Trace の検索と集約を高速に実行できます
- **時系列データをネイティブサポート**：時間ベースのデータ保持とパーティショニングを組み込みでサポートします

### Composite Storage の使用

Observability をサポートしない Provider（Convex や DynamoDB など）を使用している場合や、パフォーマンスを最適化したい場合は、[composite storage](https://mastra.zisheng.pro/ja/reference/storage/composite) を使用してください。他のデータをプライマリデータベースに保持したまま、Observability データを ClickHouse へルーティングできます。

## バッチ処理の動作

### フラッシュのトリガー

どちらのバッチ戦略（`batch-with-updates` と `insert-only`）でも、次のいずれかの条件を満たすと Trace がストレージへフラッシュされます。

1. **サイズトリガー**：バッファーが `maxBatchSize` 個の Span に達したとき
2. **時間トリガー**：最初のイベントから `maxBatchWaitMs` が経過したとき
3. **緊急フラッシュ**：バッファーが `maxBufferSize` の上限に近づいたとき
4. **シャットダウン**：保留中のすべてのイベントを強制的にフラッシュします

### エラー処理

MastraStorageExporter には、本番環境で使用できる信頼性の高いエラー処理が含まれています。

- **再試行ロジック**：指数バックオフ（500ms、1s、2s、4s）
- **一時的な失敗**：バックオフを使用して自動的に再試行します
- **永続的な失敗**：4回失敗するとバッチを破棄します
- **バッファーオーバーフロー**：ストレージ障害時のメモリ問題を防ぎます

## 破棄された Observability イベント

`DefaultExporter` は Observability データを永続化できない場合、構造化された drop イベントを発行します。`onDroppedEvent` を持つ exporter または bridge を登録すると、これらの drop をアラートまたは監視システムへ転送できます。

イベントが破棄される理由は2つあります。

- `unsupported-storage`：ストレージ Provider がシグナルタイプを実装していません。
- `retry-exhausted`：exporter がバッチを最大 `maxRetries` 回再試行した後、破棄しました。

次の例は、drop の詳細を監視エンドポイントへ転送する方法を示しています。

```typescript
import { BaseExporter } from '@mastra/observability'
import type { ObservabilityDropEvent, TracingEvent } from '@mastra/core/observability'

class DropAlertExporter extends BaseExporter {
  name = 'drop-alerts'

  async onDroppedEvent(event: ObservabilityDropEvent) {
    await fetch('https://monitoring.example.com/observability-drops', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        count: event.count,
        signal: event.signal,
        reason: event.reason,
        exporterName: event.exporterName,
      }),
    })
  }

  protected async _exportTracingEvent(_event: TracingEvent) {}
}
```

## 設定例

```typescript
// Zero config - recommended for most users
new MastraStorageExporter()

// Development override
new MastraStorageExporter({
  strategy: 'realtime', // Immediate visibility for debugging
})

// High-throughput production
new MastraStorageExporter({
  maxBatchSize: 2000, // Larger batches
  maxBatchWaitMs: 10000, // Wait longer to fill batches
  maxBufferSize: 50000, // Handle longer outages
})

// Low-latency production
new MastraStorageExporter({
  maxBatchSize: 100, // Smaller batches
  maxBatchWaitMs: 1000, // Flush quickly
})
```

## 関連情報

- [Tracing の概要](https://mastra.zisheng.pro/ja/docs/observability/tracing/overview)
- [MastraPlatformExporter](https://mastra.zisheng.pro/ja/docs/observability/integrations/exporters/mastra-platform)
- [Composite Storage](https://mastra.zisheng.pro/ja/reference/storage/composite)：複数のストレージ Provider を組み合わせます
- [ストレージの設定](https://mastra.zisheng.pro/ja/docs/storage/overview)