MastraPlatformExporter

新增於： @mastra/observability@1.12.0。較早版本（@mastra/observability@1.8.0 至 1.11.x）以已棄用的 CloudExporter 名稱匯出同一個 exporter。

將 tracing 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 - 推導項目範圍 collector 路由（例如 /projects/:projectId/ai/spans/publish）時使用的項目 ID
• MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT - 覆寫可觀測性端點。可傳入基礎來源或完整的 traces 發佈 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 平台的 tracing 事件。

只會匯出 SPAN_ENDED tracing 事件。SPAN_STARTED 及 SPAN_UPDATED 會被忽略。符合條件的 span 會加入緩衝區，並在下一次 flush 時上載至 traces 端點。

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

onLogEvent

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

處理要匯出的日誌訊號。

傳入此處理常式的每個 LogEvent 都會加入緩衝區，並匯出至從已設定基礎端點推導出的 logs 端點。與 tracing 不同，MastraPlatformExporter 層級不會進行額外的事件狀態篩選。如果 exporter 已停用，此方法不會執行任何操作。

傳回： 日誌事件獲接納並加入緩衝區後，傳回 Promise<void>。

onMetricEvent

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

處理要匯出的指標訊號。

傳入此處理常式的每個 MetricEvent 都會加入緩衝區，並匯出至從已設定基礎端點推導出的 metrics 端點。MastraPlatformExporter 內不會按指標子類型或狀態作額外篩選。除非 exporter 已停用，否則會轉送收到的每個指標事件。

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

onScoreEvent

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

處理要匯出的分數訊號。

傳入此處理常式的每個 ScoreEvent 都會加入緩衝區，並匯出至從已設定基礎端點推導出的 scores 端點。exporter 層除了檢查 exporter 是否已停用之外，不會作額外篩選，因此此方法收到的所有分數事件都會被轉送。

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

onFeedbackEvent

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

處理要匯出的意見訊號。

傳入此處理常式的每個 FeedbackEvent 都會加入緩衝區，並匯出至從已設定基礎端點推導出的 feedback 端點。MastraPlatformExporter 內不會按意見類型作篩選。除非 exporter 已停用，否則此處收到的所有意見事件都會被轉送。

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

flush

async flush(): Promise<void>

強制將緩衝區內的所有事件 flush 至 Mastra 平台，而不關閉 exporter。這適用於無伺服器環境，讓你可以確保 span 在執行階段終止前已匯出。

shutdown

async shutdown(): Promise<void>

Flush 餘下事件並執行清理。

行為

驗證

如果沒有透過設定或環境變數提供存取權杖，exporter 會：

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

批次處理

exporter 會將 tracing 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 tracing 事件
• 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 名稱的 dashboard 或警示規則，在你完成遷移前仍可繼續運作。

另請參閱

文件

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

其他 Exporter

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

參考

• 配置：配置選項
• 介面：類型定義