MastraPlatformExporter

引入版本： @mastra/observability@1.12.0。更早的版本（@mastra/observability@1.8.0 至 1.11.x）以已弃用的 CloudExporter 名称导出同一个 Exporter。

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

备注

MastraPlatformExporter 以前称为 CloudExporter。原有的 CloudExporter 类仍从 @mastra/observability 导出，因此现有 import 可以继续使用，但它已被弃用，并将在未来的主版本中移除。新代码应使用 MastraPlatformExporter。

构造函数

new MastraPlatformExporter(config?: MastraPlatformExporterConfig)

MastraPlatformExporterConfig

interface MastraPlatformExporterConfig extends BaseExporterConfig {
  /** Maximum number of buffered events per batch (spans, logs, metrics, scores, feedback). Default: 1000 */
  maxBatchSize?: number

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

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

  /** Mastra Observability access token (from env or config) */
  accessToken?: string

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

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

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

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

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

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

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

扩展自 BaseExporterConfig，其中包括：

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

环境变量

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

• MASTRA_PLATFORM_ACCESS_TOKEN - MastraPlatformExporter 请求使用的身份验证令牌
• MASTRA_PROJECT_ID - 推导项目范围的收集器路由时使用的项目 ID，例如 /projects/:projectId/ai/spans/publish
• MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT - 可观测性端点覆盖值。可传入基础源地址或完整的 Trace 发布 URL。在 @mastra/observability@1.9.2 及更高版本中，默认值为 https://observability.mastra.ai

属性

readonly name = 'mastra-platform-exporter';

为保持向后兼容，已弃用的 CloudExporter 类继续使用 'mastra-cloud-observability-exporter' 作为其 name。

方法

exportTracingEvent

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

处理要导出到 Mastra 平台的追踪事件。

仅导出 SPAN_ENDED 追踪事件。SPAN_STARTED 和 SPAN_UPDATED 会被忽略。匹配的 Span 将进入缓冲区，并在下一次 flush 时上传到 Trace 端点。

返回值： 在追踪事件被接受并进入缓冲区或被忽略后返回 Promise<void>。

onLogEvent

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

处理要导出的日志信号。

传入此处理程序的每个 LogEvent 都会进入缓冲区，并导出到根据配置的基础端点推导出的日志端点。与追踪不同，MastraPlatformExporter 层不会执行额外的事件状态过滤。如果 Exporter 已禁用，此方法不会执行任何操作。

返回值： 在日志事件被接受并进入缓冲区后返回 Promise<void>。

onMetricEvent

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

处理要导出的指标信号。

传入此处理程序的每个 MetricEvent 都会进入缓冲区，并导出到根据配置的基础端点推导出的指标端点。MastraPlatformExporter 内部不会再按指标子类型或状态进行过滤。除非 Exporter 已禁用，否则它会转发收到的每个指标事件。

返回值： 在指标事件被接受并进入缓冲区后返回 Promise<void>。

onScoreEvent

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

处理要导出的评分信号。

传入此处理程序的每个 ScoreEvent 都会进入缓冲区，并导出到根据配置的基础端点推导出的评分端点。除了检查 Exporter 是否已禁用外，Exporter 层不会执行额外过滤，因此此方法收到的所有评分事件都会被转发。

返回值： 在评分事件被接受并进入缓冲区后返回 Promise<void>。

onFeedbackEvent

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

处理要导出的反馈信号。

传入此处理程序的每个 FeedbackEvent 都会进入缓冲区，并导出到根据配置的基础端点推导出的反馈端点。MastraPlatformExporter 内部不会按反馈类型进行过滤。除非 Exporter 已禁用，否则此处收到的所有反馈事件都会被转发。

返回值： 在反馈事件被接受并进入缓冲区后返回 Promise<void>。

flush

async flush(): Promise<void>

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

shutdown

async shutdown(): Promise<void>

Flush 剩余事件并执行清理。

行为

身份验证

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

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

批处理

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

• 当缓冲区中的事件总数达到 maxBatchSize 时 flush
• 从批次中的第一个信号进入缓冲区起，经过 maxBatchWaitMs 后 flush
• 调用 shutdown() 时 flush

错误处理

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

MastraPlatformExporter 引发的错误使用 MASTRA_PLATFORM_EXPORTER_* id 前缀。已弃用的 CloudExporter 继续发出使用 CLOUD_EXPORTER_* id 的错误。

端点路由

• 基础源地址会自动推导出各信号端点
• 未设置 projectId 时，推导出的路由使用 /ai/{signal}/publish
• 设置 projectId 或 MASTRA_PROJECT_ID 后，推导出的路由使用 /projects/:projectId/ai/{signal}/publish
• 即使配置了 projectId，显式指定的完整发布 URL 也会按原样使用

信号处理

• exportTracingEvent() 仅导出 SPAN_ENDED 追踪事件
• onLogEvent()、onMetricEvent()、onScoreEvent() 和 onFeedbackEvent() 会将各自信号类型中收到的每个事件放入缓冲区
• 在 flush() 和 shutdown() 期间，所有受支持的信号批次都会上传到对应的发布端点

Span 传输格式

这里记录发送到 Mastra 平台的每个 Span 的结构，仅供参考：它不从 @mastra/observability 导出，也不应被 import。Exporter 会展开原始 AnyExportedSpan（因此会保留源字段名称），并在其上添加一小组便于平台使用的别名：

type MastraPlatformSpanRecord = AnyExportedSpan & {
  // Aliases derived from the source span
  spanId: string // alias for span.id
  spanType: string // alias for span.type
  startedAt: Date // alias for span.startTime
  endedAt: Date | null // alias for span.endTime ?? null
  error: AnyExportedSpan['errorInfo'] | null

  // Stamped at export time
  createdAt: Date
  updatedAt: Date | null
}

展开后的 AnyExportedSpan 还包含原始的 id、type、name、traceId、parentSpanId、isRootSpan、isEvent、startTime、endTime、entityType、entityId、entityName、tags、attributes、metadata、input、output 和 errorInfo。有关 AnyExportedSpan 的信息，请参阅接口。

用法

import { MastraPlatformExporter } from '@mastra/observability'

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

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

从 CloudExporter 迁移

这两个类具有相同的构造函数签名、环境变量和行为。要进行迁移，请替换 import 和构造函数：

// Before
import { CloudExporter } from '@mastra/observability'
const exporter = new CloudExporter()

// After
import { MastraPlatformExporter } from '@mastra/observability'
const exporter = new MastraPlatformExporter()

原始 CloudExporter 会保持不变，因此匹配先前 CLOUD_EXPORTER_* 错误 ID 或 mastra-cloud-observability-exporter Exporter 名称的仪表板或告警规则，可以在迁移前继续正常工作。

另请参阅

文档

• 追踪概述：完整指南
• Exporter：Exporter 概念

其他 Exporter

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

参考

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