默认导出器

🌐 Default Exporter

DefaultExporter 将痕迹持久化到你配置的存储后端，使其可以通过 Studio 访问。当使用默认的可观测性配置时，它会自动启用，并且不需要任何外部服务。

🌐 The DefaultExporter persists traces to your configured storage backend, making them accessible through Studio. It's automatically enabled when using the default observability configuration and requires no external services.

Production Observability

Observability data can quickly overwhelm general-purpose databases in production. For high-traffic applications, we recommend using ClickHouse for the observability storage domain via composite storage. See Production Recommendations for details.

配置

🌐 Configuration

先决条件

🌐 Prerequisites

1. 存储后端：配置存储提供程序（libSQL、PostgreSQL 等）
2. Studio：安装以便本地查看跟踪

基础设置

🌐 Basic Setup

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { Observability, DefaultExporter } 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 DefaultExporter()],
      },
    },
  }),
});

推荐配置

🌐 Recommended Configuration

在你的可观测性配置中包含 DefaultExporter：

🌐 Include DefaultExporter in your observability configuration:

import { Mastra } from "@mastra/core";
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  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 DefaultExporter(), // Persists traces to storage for Mastra Studio
          new CloudExporter(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(),
        ],
      },
    },
  }),
});

查看痕迹

🌐 Viewing Traces

工作室

🌐 Studio

通过 Studio 访问你的跟踪记录：

🌐 Access your traces through Studio:

1. 启动工作室
2. 导航到可观测性
3. 筛选并搜索本地轨迹
4. 查看详细的跨度信息

追踪策略

🌐 Tracing Strategies

DefaultExporter 会根据你的存储提供商自动选择最佳的跟踪策略。如果需要，你也可以覆盖此选择。

🌐 DefaultExporter automatically selects the optimal tracing strategy based on your storage provider. You can also override this selection if needed.

可用策略

🌐 Available Strategies

策略	描述	使用场景
实时	立即处理每个事件	开发、调试、低流量
批处理-含更新	缓存事件并批量写入，支持完整生命周期	低流量生产环境
仅插入	只处理已完成的跨度，忽略更新	高流量生产环境

策略配置

🌐 Strategy Configuration

new DefaultExporter({
  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 Support

不同的存储提供商支持不同的跟踪策略。一些提供商支持用于生产工作负载的可观测性，而其他提供商则主要用于本地开发。

🌐 Different storage providers support different tracing strategies. Some providers support observability for production workloads, while others are intended primarily for local development.

如果你将策略设置为 'auto'，DefaultExporter 会自动为存储提供商选择最优策略。如果你将策略设置为存储提供商不支持的模式，你会收到一条错误信息。

🌐 If you set the strategy to 'auto', the DefaultExporter automatically selects the optimal strategy for the storage provider. If you set the strategy to a mode that the storage provider doesn't support, you will get an error message.

支持可观测性的提供商

🌐 Providers with Observability Support

存储提供商	首选策略	支持的策略	推荐使用场景
ClickHouse (@mastra/clickhouse)	仅插入	仅插入	高流量生产环境
PostgreSQL	批量更新	批量更新, 仅插入	低流量生产环境
MSSQL	批量更新	批量更新, 仅插入	低流量生产环境
MongoDB	批量更新	批量更新, 仅插入	低流量生产环境
libSQL	批量更新	批量更新, 仅插入	默认存储, 适合开发

不支持可观察性的提供商

🌐 Providers without Observability Support

以下存储提供商不支持可观测性域。如果你正在使用其中一个提供商并且需要可观测性，请使用复合存储将可观测性数据路由到受支持的提供商：

🌐 The following storage providers do not support the observability domain. If you're using one of these providers and need observability, use composite storage to route observability data to a supported provider:

• Convex
• DynamoDB
• Cloudflare D1
• Cloudflare 持久化对象
• Upstash
• LanceDB

策略优势

🌐 Strategy Benefits

• 实时：即时可见，最适合调试
• 批处理更新：吞吐量提升 10-100 倍，完整的跨度生命周期
• 仅插入：数据库操作额外减少70%，非常适合分析

生产建议

🌐 Production Recommendations

在生产环境中，可观测性数据增长迅速。单次代理交互就可能生成数百个跨度，高流量应用每天可能产生数千条追踪。大多数通用数据库并未针对这种以写入为主、仅追加的工作负载进行优化。

🌐 Observability data grows quickly in production environments. A single agent interaction can generate hundreds of spans, and high-traffic applications can produce thousands of traces per day. Most general-purpose databases aren't optimized for this write-heavy, append-only workload.

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

🌐 Recommended: ClickHouse for High-Volume Production

ClickHouse 是一种面向大规模分析工作负载的列式数据库。它是生产环境可观测性的推荐选择，因为：

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

使用复合存储

🌐 Using Composite Storage

如果你使用的服务提供商不支持可观测性（例如 Convex 或 DynamoDB），或者想要优化性能，请使用 复合存储 将可观测性数据路由到 ClickHouse，同时将其他数据保留在你的主数据库中。

🌐 If you're using a provider without observability support (like Convex or DynamoDB) or want to optimize performance, use composite storage to route observability data to ClickHouse while keeping other data in your primary database.

批处理行为

🌐 Batching Behavior

刷新触发器

🌐 Flush Triggers

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

🌐 For both batch strategies (batch-with-updates and insert-only), traces are flushed to storage when any of these conditions are met:

1. 大小触发器：缓冲区到达 maxBatchSize 个跨度
2. 时间触发器：自首次事件起已过去 maxBatchWaitMs
3. 紧急刷新：缓冲区接近 maxBufferSize 限制
4. 关闭：强制刷新所有待处理事件

错误处理

🌐 Error Handling

DefaultExporter 包括用于生产环境的强大错误处理功能：

🌐 The DefaultExporter includes robust error handling for production use:

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

配置示例

🌐 Configuration Examples

// Zero config - recommended for most users
new DefaultExporter();

// Development override
new DefaultExporter({
  strategy: "realtime", // Immediate visibility for debugging
});

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

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

相关

🌐 Related

• 追踪概览
• CloudExporter
• 组合存储 - 合并多个存储提供商
• 存储配置