Storage exporter

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

备注

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

生产可观测性

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

配置

前置条件

1. 存储后端：配置一个存储提供方（libSQL、PostgreSQL 等）
2. Studio：安装以在本地查看 traces

基本设置

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 访问你的 traces：

1. 启动 Studio
2. 导航到 Observability
3. 过滤和搜索本地 traces
4. 检查详细的 span 信息

追踪策略

MastraStorageExporter 会根据你的存储提供方自动选择最优追踪策略。如有需要，你也可以覆盖此选择。

可用策略

策略	描述	使用场景
realtime	立即处理每个事件	开发、调试、低流量
batch-with-updates	缓冲事件并批量写入，支持完整生命周期	低流量生产环境
insert-only	仅处理已完成的 spans，忽略更新	高流量生产环境
event-sourced	Span 开始时写入一行，结束时再写入一行，读取时合并	高流量生产环境、进行中的 traces

策略配置

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

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

存储提供方支持

不同的存储提供方支持不同的追踪策略。一些提供方支持用于生产工作负载的可观测性，而另一些主要面向本地开发。

如果你将策略设置为 'auto'，MastraStorageExporter 会自动为存储提供方选择最优策略。如果你设置了存储提供方不支持的显式策略，导出器会记录一条警告并回退到该提供方的首选策略。

支持可观测性的提供方

存储提供方	首选策略	支持的策略	推荐用途
ClickHouse	insert-only	insert-only	生产环境（高流量）
PostgresStore	batch-with-updates	batch-with-updates, insert-only	生产环境（低流量）
PostgresStoreVNext	event-sourced	event-sourced	生产环境（高流量）
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	默认存储，适合开发

备注

在 insert-only 模式下，仅持久化已完成的 spans，span 的开始和更新事件会被忽略。因此，只有在根 span 结束后，trace 才会在 Studio 中可见，按 status: 'running' 过滤 traces 不会返回结果。PostgresStoreVNext 改用 event-sourced 追踪，因此进行中的 traces 保持可见，同时保留仅追加写入。

不支持可观测性的提供方

以下存储提供方不支持 observability 域。如果你使用这些提供方之一并且需要可观测性，请使用 composite storage将可观测性数据路由到受支持的提供方：

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

策略优势

• realtime：立即可见，最适合调试
• batch-with-updates：吞吐量提升 10-100 倍，完整的 span 生命周期
• insert-only：数据库操作额外减少 70%，非常适合分析
• event-sourced：与 insert-only 一样仅追加，但在运行执行期间，进行中的 traces 在 Studio 中保持可见

生产建议

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

推荐：高流量生产环境使用 ClickHouse

ClickHouse 是一个为高流量分析工作负载设计的列式数据库。它是生产可观测性的推荐选择，因为：

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

使用 Composite Storage

如果你使用的提供方不支持可观测性（例如 Convex 或 DynamoDB），或者希望优化性能，请使用 composite storage将可观测性数据路由到 ClickHouse，同时将其他数据保留在主数据库中。

批处理行为

刷新触发条件

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

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

错误处理

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

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

被丢弃的可观测性事件

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

事件被丢弃有两种原因：

• unsupported-storage：存储提供方未实现该信号类型。
• retry-exhausted：导出器最多重试一个批次 maxRetries 次，然后将其丢弃。

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

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

相关内容

• Traces 用法
• MastraPlatformExporter
• Composite Storage：组合多个存储提供方
• 存储配置