MastraPlatformExporter

新增於：@mastra/observability@1.12.0。較早版本（@mastra/observability@1.8.0 至 1.11.x）會將相同 exporter 匯出為已淘汰的 CloudExporter。

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

備註

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

環境變數

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

• MASTRA_PLATFORM_ACCESS_TOKEN - MastraPlatformExporter 請求的驗證 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-platform-exporter';

為了向後相容，已淘汰的 CloudExporter 類別會繼續使用 'mastra-cloud-observability-exporter' 作為其 name。

方法

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 不同，MastraPlatformExporter 層級不會額外依事件狀態篩選。Exporter 停用時，此方法會成為 no-op。

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

onMetricEvent

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

處理要匯出的指標 signal。

傳入此 handler 的每個 MetricEvent 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的指標 endpoint。MastraPlatformExporter 內部不會額外依指標子類型或狀態篩選。除非 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。MastraPlatformExporter 內部不會依回饋類型篩選。除非 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 次
• 所有重試皆失敗後捨棄批次
• 記錄錯誤，但繼續處理新事件

MastraPlatformExporter 引發的錯誤會使用 MASTRA_PLATFORM_EXPORTER_* id 前置字串。已淘汰的 CloudExporter 會繼續產生 CLOUD_EXPORTER_* id。

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

Span wire 格式

以下說明傳送至 Mastra platform 的每個 span 形狀，僅供參考：它不會從 @mastra/observability 匯出，也不應 import。Exporter 會展開原始 AnyExportedSpan（因此保留來源欄位名稱），再疊加少量適合 platform 使用的 alias：

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 名稱的 dashboard 或 alert 規則，能在您完成遷移前繼續運作。

另請參閱

文件

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

其他 Exporter

• MastraStorageExporter：儲存持久化
• ConsoleExporter：偵錯輸出
• Langfuse：Langfuse 整合
• Braintrust：Braintrust 整合

參考

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