CloudExporter

将跟踪信息发送到 Mastra Cloud 以进行在线可视化和监控。

🌐 Sends traces to Mastra Cloud for online visualization and monitoring.

构造函数

🌐 Constructor

new CloudExporter(config?: CloudExporterConfig)

CloudExporterConfig

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

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

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

  /** Cloud access token (from env or config) */
  accessToken?: string;

  /** Cloud observability endpoint */
  endpoint?: string;
}

扩展自 BaseExporterConfig，包括：

🌐 Extends BaseExporterConfig, which includes:

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

环境变量

🌐 Environment Variables

如果配置中未提供，导出器会读取这些环境变量：

🌐 The exporter reads these environment variables if not provided in config:

• MASTRA_CLOUD_ACCESS_TOKEN - 用于认证的访问令牌
• MASTRA_CLOUD_TRACES_ENDPOINT - 自定义端点（默认为 https://api.mastra.ai/ai/spans/publish）

属性

🌐 Properties

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

方法

🌐 Methods

exportTracingEvent

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

处理跟踪事件。仅将 SPAN_ENDED 事件导出到云端。

🌐 Processes tracing events. Only exports SPAN_ENDED events to Cloud.

flush

async flush(): Promise<void>

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

🌐 Force flushes any buffered events to Mastra Cloud 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 events and performs cleanup.

行为

🌐 Behavior

验证

🌐 Authentication

如果未通过配置或环境变量提供访问令牌，导出器将会：

🌐 If no access token is provided via config or environment variable, the exporter:

• 记录带有注册信息的警告
• 作为空操作运行（丢弃所有事件）

批处理

🌐 Batching

导出器将跨度批处理以提高网络使用效率：

🌐 The exporter batches spans for efficient network usage:

• 当批量大小达到 maxBatchSize 时刷新
• 当批处理中的第一个跨度经过 maxBatchWaitMs 时刷新
• shutdown() 上的刷新

错误处理

🌐 Error Handling

• 使用指数退避重试，最多 maxRetries 次
• 在所有重试失败后丢弃批次
• 记录错误，但继续处理新事件

事件处理

🌐 Event Processing

• 仅处理 SPAN_ENDED 事件
• 忽略 SPAN_STARTED 和 SPAN_UPDATED 事件
• 将跨度格式化为 MastraCloudSpanRecord 格式

MastraCloudSpanRecord

云跨度的内部格式：

🌐 Internal format for cloud spans:

interface MastraCloudSpanRecord {
  traceId: string;
  spanId: string;
  parentSpanId: string | null;
  name: string;
  spanType: string;
  attributes: Record<string, any> | null;
  metadata: Record<string, any> | null;
  startedAt: Date;
  endedAt: Date | null;
  input: any;
  output: any;
  error: any;
  isEvent: boolean;
  createdAt: Date;
  updatedAt: Date | null;
}

用法

🌐 Usage

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

// Uses environment variable for token
const exporter = new CloudExporter();

// Explicit configuration
const customExporter = new CloudExporter({
  accessToken: "your-token",
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  logLevel: 'debug'
});

另请参阅

🌐 See Also

文档

🌐 Documentation

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

其他导出器

🌐 Other Exporters

• DefaultExporter - 存储持久化
• ConsoleExporter - 调试输出
• Langfuse - Langfuse 集成
• Braintrust - Braintrust 集成

参考

🌐 Reference

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