CloudExporter

新增於：@mastra/observability@1.8.0。自 1.12.0 起已淘汰，請改用 MastraPlatformExporter。

將 tracing span、log、指標、分數與回饋傳送至 Mastra platform，以供線上視覺化與監控。

已淘汰

保留 CloudExporter 是為了向後相容，並會在未來的主要版本中移除。新專案請使用 MastraPlatformExporter。兩個類別具有相同的建構函式、環境變數與 runtime 行為；CloudExporter 會保留原本的 mastra-cloud-observability-exporter exporter name 與 CLOUD_EXPORTER_* 錯誤 ID，讓以此建立的監控規則能繼續運作。

建構函式

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' - Log 層級（預設：INFO）

環境變數

若設定中未提供，exporter 會讀取下列環境變數：

• MASTRA_PLATFORM_ACCESS_TOKEN - CloudExporter 請求的驗證 token
• MASTRA_PROJECT_ID - 推導專案範圍 collector route（例如 /projects/:projectId/ai/spans/publish）時使用的 Project ID
• MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT - 可觀測性 endpoint 覆寫值。可傳入 base origin 或完整的 trace 發布 URL。@mastra/observability@1.9.2 及更新版本預設為 https://observability.mastra.ai

屬性

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

方法

exportTracingEvent

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

處理要匯出至 Mastra platform 的 tracing 事件。

只會匯出 SPAN_ENDED tracing 事件。SPAN_STARTED 與 SPAN_UPDATED 會被忽略。相符的 span 會先進入 buffer，並在下次 flush 時上傳至 trace endpoint。

**傳回：**tracing 事件已接受進入 buffer 或被忽略後，傳回 Promise<void>。

onLogEvent

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

處理要匯出的 log signal。

傳入此 handler 的每個 LogEvent 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的 log endpoint。與 tracing 不同，CloudExporter 層級不會額外依事件狀態篩選。Exporter 停用時，此方法會成為 no-op。

**傳回：**log 事件已接受進入 buffer 後，傳回 Promise<void>。

onMetricEvent

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

處理要匯出的指標 signal。

傳入此 handler 的每個 MetricEvent 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的指標 endpoint。CloudExporter 內部不會額外依指標子類型或狀態篩選。除非 exporter 已停用，否則會轉送收到的每個指標事件。

**傳回：**指標事件已接受進入 buffer 後，傳回 Promise<void>。

onScoreEvent

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

處理要匯出的分數 signal。

傳入此 handler 的每個 ScoreEvent 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的分數 endpoint。Exporter 層級除了檢查是否停用外，不會額外篩選，因此此方法收到的所有分數事件都會轉送。

**傳回：**分數事件已接受進入 buffer 後，傳回 Promise<void>。

onFeedbackEvent

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

處理要匯出的回饋 signal。

傳入此 handler 的每個 FeedbackEvent 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的回饋 endpoint。CloudExporter 內部不會依回饋類型篩選。除非 exporter 已停用，否則會轉送此處收到的所有回饋事件。

**傳回：**回饋事件已接受進入 buffer 後，傳回 Promise<void>。

flush

async flush(): Promise<void>

強制將所有緩衝事件 flush 至 Mastra platform，而不關閉 exporter。這在 serverless 環境中特別實用，可確保 runtime 結束前已匯出 span。

shutdown

async shutdown(): Promise<void>

Flush 其餘事件並執行清理。

行為

驗證

若未透過設定或環境變數提供 access token，exporter 將會：

• 記錄包含註冊資訊的警告
• 以 no-op 方式運作（捨棄所有事件）

批次處理

Exporter 會批次處理 tracing span、log、指標、分數與回饋，以有效運用網路：

• 緩衝事件總數達到 maxBatchSize 時 flush
• 從批次中的第一個緩衝 signal 開始經過 maxBatchWaitMs 時 flush
• 呼叫 shutdown() 時 flush

錯誤處理

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

Endpoint 路由

• Base origin 會自動推導 signal endpoint
• 沒有 projectId 時，推導出的 route 使用 /ai/{signal}/publish
• 有 projectId 或 MASTRA_PROJECT_ID 時，推導出的 route 使用 /projects/:projectId/ai/{signal}/publish
• 即使已設定 projectId，明確的完整發布 URL 仍會原樣使用

Signal 處理

• exportTracingEvent() 只匯出 SPAN_ENDED tracing 事件
• onLogEvent()、onMetricEvent()、onScoreEvent() 與 onFeedbackEvent() 會針對各自的 signal 類型，將收到的每個事件放入 buffer
• flush() 與 shutdown() 期間，所有支援的 signal 批次都會上傳至相符的發布 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 整合

參考

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