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

# Mastra Storage exporter

`MastraStorageExporter` 会将 Trace 持久化到配置的存储后端，使其可以通过 Studio 访问。它不需要外部服务。

> **备注:** `MastraStorageExporter` 以前名为 `DefaultExporter`。为向后兼容，原来的 `DefaultExporter` 类仍从 `@mastra/observability` 导出，但已弃用。新代码应使用 `MastraStorageExporter`。

> **生产环境可观测性:** 在生产环境中，可观测性数据可能很快压垮通用数据库。对于高流量应用，请通过 [composite storage](https://mastra.zisheng.pro/reference/storage/composite) 将 observability storage domain 路由到 [ClickHouse](https://mastra.zisheng.pro/reference/storage/clickhouse)。详情请参阅[生产环境建议](#production-recommendations)。

## 配置

### 前提条件

1. **存储后端**：配置 storage Provider（libSQL、PostgreSQL 等）
2. **Studio**：安装 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()],
      },
    },
  }),
})
```

### 推荐配置

在可观测性配置中包含 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 会根据 storage 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
})
```

## Storage Provider 支持

不同 storage Provider 支持不同的 Tracing 策略。部分 Provider 支持生产工作负载的可观测性，其他则主要面向本地开发。

如果将策略设为 `'auto'`，`MastraStorageExporter` 会自动为 storage Provider 选择最优策略。如果显式设置了 Provider 不支持的策略，exporter 会记录警告并回退到该 Provider 的首选策略。

### 支持可观测性的 Provider

| Storage Provider                                                          | 首选策略               | 支持的策略                           | 建议用途      |
| ------------------------------------------------------------------------- | ------------------ | ------------------------------- | --------- |
| **[ClickHouse](https://mastra.zisheng.pro/reference/storage/clickhouse)** | insert-only        | insert-only                     | 生产环境（高流量） |
| **[PostgreSQL](https://mastra.zisheng.pro/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | 生产环境（低流量） |
| **[MSSQL](https://mastra.zisheng.pro/reference/storage/mssql)**           | batch-with-updates | batch-with-updates, insert-only | 生产环境（低流量） |
| **[MongoDB](https://mastra.zisheng.pro/reference/storage/mongodb)**       | batch-with-updates | batch-with-updates, insert-only | 生产环境（低流量） |
| **[OracleDB](https://mastra.zisheng.pro/reference/storage/oracledb)**     | batch-with-updates | batch-with-updates, insert-only | 生产环境（低流量） |
| **[libSQL](https://mastra.zisheng.pro/reference/storage/libsql)**         | batch-with-updates | batch-with-updates, insert-only | 默认存储，适合开发 |

### 不支持可观测性的 Provider

以下 storage Provider **不支持** observability domain。如果你使用其中之一且需要可观测性，请使用 [composite storage](https://mastra.zisheng.pro/reference/storage/composite) 将可观测性数据路由到支持的 Provider：

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

### 策略优势

- **realtime**：立即可见，最适合调试
- **batch-with-updates**：吞吐量提升 10–100 倍，支持完整 span 生命周期
- **insert-only**：数据库操作进一步减少 70%，非常适合分析

## 生产环境建议

可观测性数据在生产环境中增长很快。一次 Agent 交互可能产生数百个 span，高流量应用每天可能产生数千条 Trace。大多数通用数据库并未针对这种写入密集、仅追加的工作负载进行优化。

### 建议：高流量生产环境使用 ClickHouse

[ClickHouse](https://mastra.zisheng.pro/reference/storage/clickhouse) 是专为高流量分析工作负载设计的列式数据库。建议将它用于生产环境可观测性，原因如下：

- **针对写入优化**：每秒可处理数百万次插入
- **高效压缩**：降低 Trace 数据的存储成本
- **快速查询**：列式存储可实现快速 Trace 查找和聚合
- **原生时间序列支持**：内置基于时间的数据保留和分区支持

### 使用 Composite Storage

如果正在使用不支持可观测性的 Provider（如 Convex 或 DynamoDB），或希望优化性能，请使用 [composite storage](https://mastra.zisheng.pro/reference/storage/composite) 将可观测性数据路由到 ClickHouse，同时将其他数据保留在主数据库中。

## 批处理行为

### 刷新触发条件

对于两种批处理策略（`batch-with-updates` 和 `insert-only`），满足以下任一条件时，Trace 会刷新到存储：

1. **大小触发**：缓冲区达到 `maxBatchSize` 个 span
2. **时间触发**：从第一个事件开始经过 `maxBatchWaitMs`
3. **紧急刷新**：缓冲区接近 `maxBufferSize` 限制
4. **关闭**：强制刷新所有待处理事件

### 错误处理

MastraStorageExporter 包含适用于生产环境的可靠错误处理：

- **重试逻辑**：指数退避（500ms、1s、2s、4s）
- **暂时性失败**：使用退避自动重试
- **持续性失败**：失败 4 次后丢弃批次
- **缓冲区溢出**：在存储中断期间防止内存问题

## 丢弃的可观测性事件

当 `DefaultExporter` 无法持久化可观测性数据时，会发出结构化的丢弃事件。注册带有 `onDroppedEvent` 的 exporter 或 bridge，将这些丢弃事件转发到告警或监控系统。

事件会因以下两种原因被丢弃：

- `unsupported-storage`：storage Provider 未实现该信号类型。
- `retry-exhausted`：exporter 最多重试批次 `maxRetries` 次，随后将其丢弃。

以下示例演示如何将丢弃详情转发到监控 endpoint：

```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/docs/observability/tracing/overview)
- [MastraPlatformExporter](https://mastra.zisheng.pro/docs/observability/integrations/exporters/mastra-platform)
- [Composite Storage](https://mastra.zisheng.pro/reference/storage/composite)：组合多个 storage Provider
- [存储配置](https://mastra.zisheng.pro/docs/storage/overview)