Mastra Storage exporter

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

备注

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

生产环境可观测性

在生产环境中，可观测性数据可能很快压垮通用数据库。对于高流量应用，请通过 composite storage 将 observability storage domain 路由到 ClickHouse。详情请参阅生产环境建议。

配置

前提条件

1. 存储后端：配置 storage Provider（libSQL、PostgreSQL 等）
2. Studio：安装 Studio 以在本地查看 Trace

基本设置

src/mastra/index.ts

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：

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，忽略更新	高流量生产环境

策略配置

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	insert-only	insert-only	生产环境（高流量）
PostgreSQL	batch-with-updates	batch-with-updates, insert-only	生产环境（低流量）
MSSQL	batch-with-updates	batch-with-updates, insert-only	生产环境（低流量）
MongoDB	batch-with-updates	batch-with-updates, insert-only	生产环境（低流量）
OracleDB	batch-with-updates	batch-with-updates, insert-only	生产环境（低流量）
libSQL	batch-with-updates	batch-with-updates, insert-only	默认存储，适合开发

不支持可观测性的 Provider

以下 storage Provider 不支持 observability domain。如果你使用其中之一且需要可观测性，请使用 composite storage 将可观测性数据路由到支持的 Provider：

• Convex
• DynamoDB
• Cloudflare D1
• Cloudflare Durable Objects
• Upstash
• LanceDB

策略优势

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

生产环境建议

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

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

ClickHouse 是专为高流量分析工作负载设计的列式数据库。建议将它用于生产环境可观测性，原因如下：

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

使用 Composite Storage

如果正在使用不支持可观测性的 Provider（如 Convex 或 DynamoDB），或希望优化性能，请使用 composite storage 将可观测性数据路由到 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：

src/mastra/observability.ts

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) {}
}

配置示例

// 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 概览
• MastraPlatformExporter
• Composite Storage：组合多个 storage Provider
• 存储配置