Mastra 平台 exporter

MastraPlatformExporter 會將 traces、日誌、指標、評分及意見傳送至 Mastra 平台。你可以使用它，將任何 Mastra 應用程式的可觀測性資料路由至 Mastra 平台上託管的項目。

備註

MastraPlatformExporter 之前稱為 CloudExporter。為了向後兼容，原有的 CloudExporter class 仍會從 @mastra/observability export，但已棄用。新程式碼應使用 MastraPlatformExporter。

自行託管或獨立的應用程式

如果你在自己的基礎設施上託管 Mastra 應用程式（而非 Mastra 平台），仍需要一個已部署的 Studio 項目，才能查看 traces、日誌及指標。MastraPlatformExporter 會將資料傳送至 Studio 項目，因此你必須先建立該項目才能使用它。

1. 如果你尚未有 Mastra 項目，請先建立 Mastra 項目。
2. 使用 mastra studio deploy 將 Studio 部署至 Mastra 平台。
3. 按照下方的快速開始步驟建立存取權杖並找出項目 ID。

版本兼容性

• MastraPlatformExporter 從 @mastra/observability@1.12.0 起提供。在 1.8.0 至 1.11.x 版本中，同一個 exporter 僅以 CloudExporter 名稱提供。constructor signature 及環境變數完全相同。
• 在 @mastra/observability@1.8.0 至 1.9.1 中，除了 MASTRA_PLATFORM_ACCESS_TOKEN 和 MASTRA_PROJECT_ID 外，亦須設定 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai。
• 從 @mastra/observability@1.9.2 起，exporter 預設使用 https://observability.mastra.ai，因此只有在你想將遙測資料傳送至其他 collector 時，才需要設定 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT。

快速開始

要連接 MastraPlatformExporter，請建立存取權杖、找出目標 projectId，然後將 exporter 加入可觀測性設定。

1. 建立存取權杖

執行以下命令：

mastra auth tokens create exporter-token

此命令會輸出權杖密鑰，你可以將它用作 MASTRA_PLATFORM_ACCESS_TOKEN。

如果你已有存取權杖，則可改為從 Mastra 平台複製 Observability 的值。你可以在以下其中一處找到它：

• 在 Projects 頁面開啟項目清單，然後在項目卡片上找出 Observability 一列。
• 在項目的 Overview 頁面，於部署 URL 正下方找出 Observability 一列。

將權杖設定為環境變數：

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>

2. 找出你的 projectId

執行以下命令：

mastra studio deploy list

輸出類似如下：

✅ <your-project-name> (<your-project-id>)
   Latest:   00000000-0000-0000-0000-000000000000 — running
   URL:      https://260407.studio.mastra.cloud

在此輸出中，括號內的值就是 projectId：

<your-project-id>

將它設定為環境變數：

.env

MASTRA_PROJECT_ID=<your-project-id>

3. 設定環境變數

在你的環境中設定這兩個值，讓 MastraPlatformExporter 能夠驗證身分，並將遙測資料路由至正確的項目：

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
MASTRA_PROJECT_ID=<your-project-id>

如果你使用 @mastra/observability@1.8.0 至 1.9.1，亦須明確設定 Mastra 平台 collector：

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai

如果你想將遙測資料傳送至 Mastra 平台以外的位置，亦須設定 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT。你可以傳入 base origin，或以 /spans/publish 結尾的完整 traces publish URL。

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

傳入 base origin 時，MastraPlatformExporter 會自動衍生 traces、日誌、指標、評分及意見所對應的 publish URL。

4. 啟用 MastraPlatformExporter

以下範例示範如何將 MastraPlatformExporter 加入可觀測性設定：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraPlatformExporter } from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'api-server',
        exporters: [new MastraPlatformExporter()],
      },
    },
  }),
})

請在可觀測性設定上設定 serviceName，而非在 MastraPlatformExporter 本身設定。

請使用穩定的 serviceName 值。在 Studio 中，你可以按 Deployments → Service Name 篩選 traces，因此使用一致的名稱可讓 traces 更容易找到。

請參閱可觀測性設定參考，了解完整的可觀測性設定結構。

你亦可以選擇完全依賴環境變數：

src/mastra/index.ts

new MastraPlatformExporter()

設定 MASTRA_PLATFORM_ACCESS_TOKEN 和 MASTRA_PROJECT_ID 後，MastraPlatformExporter 會將資料傳送至你所設定的 Mastra 平台項目。如果你亦設定了 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT，則會改為將資料傳送至該 collector。請參閱 MastraPlatformExporter 參考，了解完整的設定選項清單。

建議設定

如果你亦想在 Studio 中檢視本機 traces，或將可觀測性資料持久儲存至已設定的儲存空間，請加入 MastraStorageExporter。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

完整設定

MastraPlatformExporter 預設使用 Mastra 平台。如果你想將遙測資料傳送至其他 collector，請在環境中設定 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT，或在程式碼中傳入 endpoint。

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

以下範例示範如何在程式碼中覆寫 collector endpoint 及批次處理行為：

src/mastra/index.ts

new MastraPlatformExporter({
  endpoint: 'https://collector.example.com',
  maxBatchSize: 1000,
  maxBatchWaitMs: 5000,
  logLevel: 'info',
})

在 Mastra Studio 中查看資料

啟用 MastraPlatformExporter 後，在 Mastra Studio 中開啟你的項目，以檢視已 export 的資料。

• 開啟你為 MASTRA_PROJECT_ID 設定的項目，然後選擇 Open Studio。
• 在 Studio 中前往 Traces，以檢視 Agent 及 Workflow traces。
• 開啟篩選選單，並使用 Deployments → Service Name，將來自特定應用程式或部署的 traces 篩選出來。
• 使用項目控制台中的 Logs 頁面檢視已 export 的日誌。

使用 Mastra Studio 部署時，請將 Deployment → Service Name 設為穩定的值，並確保它與可觀測性設定中的 serviceName 一致。當多個服務或部署將資料傳送至同一個項目時，這可讓你更容易在 Studio 中透過 Deployments → Service Name 篩選 traces。

效能

資訊

MastraPlatformExporter 使用批次處理來優化網絡用量。事件會先暫存，再分批傳送，從而減少額外開銷，同時維持近乎即時的可見性。

批次處理行為

• 事件會分批處理，每批最多 maxBatchSize 個（預設：1000）。
• 批次滿載或經過 maxBatchWaitMs（預設：5 秒）後便會傳送。
• 傳送失敗的批次會以指數退避方式重試。
• 如果無法連接 Mastra Studio，exporter 會妥善降級。

相關內容

• Tracing 概覽
• MastraStorageExporter