CloudExporter

添加于：@mastra/observability@1.8.0。自 1.12.0 起弃用，请改用 MastraPlatformExporter。

已弃用

为保持向后兼容，CloudExporter 目前仍予以保留，但将在未来的主要版本中移除。新项目请使用 MastraPlatformExporter。两个类使用相同的构造函数、环境变量和运行时行为；CloudExporter 会保留原有的 mastra-cloud-observability-exporter Exporter name 和 CLOUD_EXPORTER_* 错误 ID，确保基于它们构建的监控规则继续正常工作。

将 Tracing Span、日志、指标、score 和反馈发送到 Mastra 平台，以便在线可视化和监控。

构造函数

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

  /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */
  projectId?: string

  /** Base cloud observability endpoint */
  endpoint?: string

  /** Explicit cloud traces endpoint override */
  tracesEndpoint?: string

  /** Explicit cloud logs endpoint override */
  logsEndpoint?: string

  /** Explicit cloud metrics endpoint override */
  metricsEndpoint?: string

  /** Explicit cloud scores endpoint override */
  scoresEndpoint?: string

  /** Explicit cloud feedback endpoint override */
  feedbackEndpoint?: string
}

扩展 BaseExporterConfig，其中包含：

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

环境变量

如果配置中未提供相应选项，Exporter 会读取以下环境变量：

• MASTRA_PLATFORM_ACCESS_TOKEN - CloudExporter 请求的身份验证 token
• MASTRA_PROJECT_ID - 用于派生项目级 collector 路由（例如 /projects/:projectId/ai/spans/publish）的项目 ID
• MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT - 覆盖可观测性 endpoint。可传入 base origin 或完整的 Trace publish URL。在 @mastra/observability@1.9.2 及更高版本中，默认值为 https://observability.mastra.ai

属性

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

方法

exportTracingEvent

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

处理要导出到 Cloud 的 Tracing 事件。

仅导出 SPAN_ENDED Tracing 事件。SPAN_STARTED 和 SPAN_UPDATED 会被忽略。匹配的 Span 会进入缓冲区，并在下次刷新时上传到 Cloud Trace endpoint。

返回： Tracing 事件进入缓冲区或被忽略后返回 Promise<void>。

onLogEvent

async onLogEvent(event: LogEvent): Promise<void>

处理要导出到 Cloud 的日志信号。

传入此 handler 的每个 LogEvent 都会进入缓冲区，并导出到根据所配置 base endpoint 派生的 Cloud 日志 endpoint。与 Tracing 不同，CloudExporter 层不会进行额外的事件状态筛选。如果 Exporter 已被禁用，此方法不执行任何操作。

返回： 日志事件进入缓冲区后返回 Promise<void>。

onMetricEvent

async onMetricEvent(event: MetricEvent): Promise<void>

处理要导出到 Cloud 的指标信号。

传入此 handler 的每个 MetricEvent 都会进入缓冲区，并导出到根据所配置 base endpoint 派生的 Cloud 指标 endpoint。CloudExporter 内部不会按指标子类型或状态进行额外筛选。除非 Exporter 已被禁用，否则会转发收到的每个指标事件。

返回： 指标事件进入缓冲区后返回 Promise<void>。

onScoreEvent

async onScoreEvent(event: ScoreEvent): Promise<void>

处理要导出到 Cloud 的 score 信号。

传入此 handler 的每个 ScoreEvent 都会进入缓冲区，并导出到根据所配置 base endpoint 派生的 Cloud score endpoint。除检查 Exporter 是否被禁用外，Exporter 层不会进行其他筛选，因此此方法收到的所有 score 事件都会被转发。

返回： score 事件进入缓冲区后返回 Promise<void>。

onFeedbackEvent

async onFeedbackEvent(event: FeedbackEvent): Promise<void>

处理要导出到 Cloud 的反馈信号。

传入此 handler 的每个 FeedbackEvent 都会进入缓冲区，并导出到根据所配置 base endpoint 派生的 Cloud 反馈 endpoint。CloudExporter 内部不会按反馈类型进行筛选。除非 Exporter 已被禁用，否则会转发此处收到的所有反馈事件。

返回： 反馈事件进入缓冲区后返回 Promise<void>。

flush

async flush(): Promise<void>

强制将缓冲区中的所有事件刷新到 Mastra 平台，而不关闭 Exporter。适用于需要确保运行时终止前已导出 Span 的 serverless 环境。

shutdown

async shutdown(): Promise<void>

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

行为

身份验证

如果未通过配置或环境变量提供 access token，Exporter 将：

• 记录包含注册信息的警告
• 不执行任何操作（丢弃所有事件）

批处理

Exporter 会对 Tracing Span、日志、指标、score 和反馈进行批处理，以提高网络使用效率：

• 缓冲事件总数达到 maxBatchSize 时刷新
• 从该批次的第一个缓冲信号开始经过 maxBatchWaitMs 后刷新
• 调用 shutdown() 时刷新

错误处理

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

Endpoint 路由

• 根据 base origin 自动派生各信号的 endpoint
• 没有 projectId 时，派生路由使用 /ai/{signal}/publish
• 设置 projectId 或 MASTRA_PROJECT_ID 时，派生路由使用 /projects/:projectId/ai/{signal}/publish
• 即使配置了 projectId，显式提供的完整 publish URL 也会按原样使用

信号处理

• exportTracingEvent() 仅导出 SPAN_ENDED Tracing 事件
• onLogEvent()、onMetricEvent()、onScoreEvent() 和 onFeedbackEvent() 会缓冲各自收到的每个信号类型事件
• 调用 flush() 和 shutdown() 时，所有受支持的信号批次都会上传到相应的 Cloud publish endpoint

MastraCloudSpanRecord

Cloud Span 的内部格式：

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
}

用法

import { CloudExporter } from '@mastra/observability'

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

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

另请参阅

文档

• Tracing 概览：完整指南
• Exporter：Exporter 概念

其他 Exporter

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

参考

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