CloudExporter

新增於： @mastra/observability@1.8.0。於 1.12.0 棄用，由 MastraPlatformExporter 取代。

已棄用

保留 CloudExporter 是為了向後兼容，並將於未來的主要版本移除。新項目請使用 MastraPlatformExporter。兩個類別使用相同的建構函式、環境變數及執行階段行為；CloudExporter 會保留原有的 mastra-cloud-observability-exporter 匯出器 name 及 CLOUD_EXPORTER_* 錯誤 ID，確保以它建立的監察規則繼續運作。

將 tracing span、日誌、指標、分數及意見回饋傳送至 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）

環境變數

如設定中未有提供，匯出器會讀取以下環境變數：

• MASTRA_PLATFORM_ACCESS_TOKEN - CloudExporter 請求的驗證權杖
• MASTRA_PROJECT_ID - 衍生項目範圍收集器路由（例如 /projects/:projectId/ai/spans/publish）時使用的項目 ID
• MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT - 可觀測性端點覆寫值。可傳入基礎來源或完整的 trace 發佈 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 端點。

傳回： tracing 事件獲接受並加入緩衝，或被忽略後傳回 Promise<void>。

onLogEvent

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

處理供 Cloud 匯出的記錄訊號。

傳入此處理常式的每個 LogEvent 都會經過緩衝，並匯出至由已配置基礎端點衍生的 Cloud 記錄端點。與 tracing 不同，CloudExporter 層級不會再按事件狀態篩選。如匯出器已停用，此方法不會執行任何操作。

傳回： 記錄事件獲接受並加入緩衝後傳回 Promise<void>。

onMetricEvent

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

處理供 Cloud 匯出的指標訊號。

傳入此處理常式的每個 MetricEvent 都會經過緩衝，並匯出至由已配置基礎端點衍生的 Cloud 指標端點。CloudExporter 內不會再按指標子類型或狀態篩選。除非匯出器已停用，否則它會轉送收到的每個指標事件。

傳回： 指標事件獲接受並加入緩衝後傳回 Promise<void>。

onScoreEvent

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

處理供 Cloud 匯出的分數訊號。

傳入此處理常式的每個 ScoreEvent 都會經過緩衝，並匯出至由已配置基礎端點衍生的 Cloud 分數端點。匯出器層除了檢查匯出器是否已停用外，不會作額外篩選，因此此方法會轉送收到的所有分數事件。

傳回： 分數事件獲接受並加入緩衝後傳回 Promise<void>。

onFeedbackEvent

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

處理供 Cloud 匯出的意見回饋訊號。

傳入此處理常式的每個 FeedbackEvent 都會經過緩衝，並匯出至由已配置基礎端點衍生的 Cloud 意見回饋端點。CloudExporter 內不會按意見回饋類型篩選。除非匯出器已停用，否則此處收到的所有意見回饋事件都會被轉送。

傳回： 意見回饋事件獲接受並加入緩衝後傳回 Promise<void>。

flush

async flush(): Promise<void>

在不關閉匯出器的情況下，強制將所有已緩衝事件刷新至 Mastra 平台。適用於無伺服器環境，讓你可確保在執行階段終止前匯出 span。

shutdown

async shutdown(): Promise<void>

刷新其餘事件並執行清理。

行為

驗證

如未透過設定或環境變數提供存取權杖，匯出器會：

• 記錄包含註冊資料的警告
• 不執行任何操作（捨棄所有事件）

批次處理

匯出器會對 tracing span、日誌、指標、分數及意見回饋進行批次處理，以有效運用網絡：

• 已緩衝事件總數達到 maxBatchSize 時刷新
• 自批次中第一個已緩衝訊號起經過 maxBatchWaitMs 時刷新
• 呼叫 shutdown() 時刷新

錯誤處理

• 使用指數退避重試，最多嘗試 maxRetries 次
• 所有重試均失敗後捨棄批次
• 記錄錯誤，但繼續處理新事件

端點路由

• 基礎來源會自動衍生訊號端點
• 如沒有 projectId，衍生路由會使用 /ai/{signal}/publish
• 如有 projectId 或 MASTRA_PROJECT_ID，衍生路由會使用 /projects/:projectId/ai/{signal}/publish
• 即使已配置 projectId，明確指定的完整發佈 URL 亦會原樣使用

訊號處理

• exportTracingEvent() 只會匯出 SPAN_ENDED tracing 事件
• onLogEvent()、onMetricEvent()、onScoreEvent() 及 onFeedbackEvent() 會緩衝各自收到的每個訊號類型事件
• 在 flush() 及 shutdown() 期間，所有受支援的訊號批次都會上載至各自相符的 Cloud 發佈端點

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 概覽：完整指南
• 匯出器：匯出器概念

其他匯出器

• DefaultExporter：儲存持久化
• ConsoleExporter：除錯輸出
• Langfuse：Langfuse 整合
• Braintrust：Braintrust 整合

參考

• 設定：設定選項
• 介面：類型定義