DefaultExporter

将跟踪信息持久化到 Mastra 配置的存储中，具有自动批处理和重试逻辑。

🌐 Persists traces to Mastra's configured storage with automatic batching and retry logic.

构造函数

🌐 Constructor

new DefaultExporter(config?: DefaultExporterConfig)

DefaultExporterConfig

interface DefaultExporterConfig extends BaseExporterConfig {
  /** Maximum number of spans per batch. Default: 1000 */
  maxBatchSize?: number;

  /** Maximum total buffer size before emergency flush. Default: 10000 */
  maxBufferSize?: number;

  /** Maximum time to wait before flushing batch in milliseconds. Default: 5000 */
  maxBatchWaitMs?: number;

  /** Maximum number of retry attempts. Default: 4 */
  maxRetries?: number;

  /** Base retry delay in milliseconds (uses exponential backoff). Default: 500 */
  retryDelayMs?: number;

  /** Tracing storage strategy or 'auto' for automatic selection. Default: 'auto' */
  strategy?: TracingStorageStrategy | "auto";
}

扩展自 BaseExporterConfig，包括：

🌐 Extends BaseExporterConfig, which includes:

• logger?: IMastraLogger - 记录器实例
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - 日志级别（默认：INFO）

TracingStorageStrategy

type TracingStorageStrategy = "realtime" | "batch-with-updates" | "insert-only";

策略行为

🌐 Strategy Behaviors

• 实时：立即将每个事件保存到存储中
• 批量更新：批量分别创建和更新，按顺序应用
• 仅插入：仅处理 SPAN_ENDED 事件，忽略更新

属性

🌐 Properties

readonly name = 'mastra-default-observability-exporter';

方法

🌐 Methods

init

init(options: InitExporterOptions): void

在依赖准备就绪后初始化导出器。根据存储能力确定跟踪策略。

🌐 Initializes the exporter after dependencies are ready. Resolves tracing strategy based on storage capabilities.

exportTracingEvent

async exportTracingEvent(event: TracingEvent): Promise<void>

根据已确定的策略处理跟踪事件。

🌐 Processes a tracing event according to the resolved strategy.

flush

async flush(): Promise<void>

强制将任何缓冲的事件刷新到存储，而不关闭导出器。在无服务器环境中非常有用，因为你需要确保在运行时终止之前导出跨度。

🌐 Force flushes any buffered events to storage without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.

shutdown

async shutdown(): Promise<void>

刷新剩余的缓冲事件并执行清理。

🌐 Flushes remaining buffered events and performs cleanup.

自动策略选择

🌐 Automatic Strategy Selection

当 strategy: 'auto'（默认）时，导出器会查询存储适配器的功能：

🌐 When strategy: 'auto' (default), the exporter queries the storage adapter for its capabilities:

interface TracingStrategy {
  /** Strategies supported by this adapter */
  supported: TracingStorageStrategy[];

  /** Preferred strategy for optimal performance */
  preferred: TracingStorageStrategy;
}

导出器将会：

🌐 The exporter will:

1. 如果可用，请使用存储适配器的首选策略
2. 如果首选不可用，则退回到第一个支持的策略
3. 如果不支持用户指定的策略，则记录警告

批处理行为

🌐 Batching Behavior

刷新触发器

🌐 Flush Triggers

当满足以下任何条件时，缓冲区将被刷新：

🌐 The buffer flushes when any of these conditions are met:

• 缓冲区大小达到 maxBatchSize
• 自第一个缓冲事件以来的时间超过 maxBatchWaitMs
• 缓冲区大小达到 maxBufferSize（紧急刷新）
• shutdown() 被称为

重试逻辑

🌐 Retry Logic

失败的刷新会以指数退避重试：

🌐 Failed flushes are retried with exponential backoff:

• 重试延迟：retryDelayMs * 2^attempt
• 最大尝试次数：maxRetries
• 在所有重试失败后，批处理被放弃

乱序处理

🌐 Out-of-Order Handling

针对 batch-with-updates 策略：

🌐 For batch-with-updates strategy:

• 跟踪已创建的跨度
• 拒绝尚未创建的跨度的更新/结束
• 记录乱序事件的警告
• 维护有序更新的序列号

用法

🌐 Usage

import { DefaultExporter } from "@mastra/observability";

// Default configuration
const exporter = new DefaultExporter();

// Custom batching configuration
const customExporter = new DefaultExporter({
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  strategy: "batch-with-updates",
  logLevel: 'debug'
});

另请参阅

🌐 See Also

文档

🌐 Documentation

• 追踪概览 - 完整指南
• 导出器 - 导出器概念

其他导出器

🌐 Other Exporters

• CloudExporter - Mastra 云
• ConsoleExporter - 调试输出
• Langfuse - Langfuse 集成
• Braintrust - Braintrust 集成

参考

🌐 Reference

• 配置 - 配置选项
• 接口 - 类型定义