Mastra 平台 Exporter

MastraPlatformExporter 會將 Trace、Log、指標、score 與 Feedback 傳送至 Mastra 平台。你可以使用它，將任何 Mastra 應用程式的 Observability 資料導向 Mastra 平台上的代管專案。

備註

MastraPlatformExporter 先前稱為 CloudExporter。為維持向後相容性，@mastra/observability 仍會匯出原本的 CloudExporter class，但該 class 已棄用。新程式碼應使用 MastraPlatformExporter。

自行代管或獨立應用程式

如果你在自己的基礎架構上代管 Mastra 應用程式（而不是 Mastra 平台），仍需要已部署的 Studio 專案才能查看 Trace、Log 與指標。MastraPlatformExporter 會將資料傳送至 Studio 專案，因此使用前必須先建立該專案。

1. 如果還沒有 Mastra 專案，請先建立 Mastra 專案。
2. 使用 mastra studio deploy 將 Studio 部署至 Mastra 平台。
3. 依照下方快速入門步驟建立 access token，並找出你的 Project 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。因此，只有要將 telemetry 傳送至其他 collector 時，才需要設定 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT。

快速入門

若要連線 MastraPlatformExporter，請建立 access token、找出目的地 projectId，並將 Exporter 加入 Observability 設定。

1. 建立 access token

執行下列命令：

mastra auth tokens create exporter-token

此命令會輸出可作為 MASTRA_PLATFORM_ACCESS_TOKEN 使用的 token secret。

如果已有 access token，則可改從 Mastra 平台複製 Observability 值。你可以在下列任一位置找到該值：

• 在 Projects 頁面開啟專案清單，然後在專案卡片上找到 Observability 列。
• 在專案的 Overview 頁面中，找到部署 URL 正下方的 Observability 列。

將 token 設為環境變數：

.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 能夠驗證身分，並將 telemetry 導向正確的專案：

.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

如果要將 telemetry 傳送至 Mastra 平台以外的位置，也請設定 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT。請傳入 base origin，或以 /spans/publish 結尾的完整 Trace 發布 URL。

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

傳入 base origin 時，MastraPlatformExporter 會自動推導 Trace、Log、指標、score 與 Feedback 對應的發布 URL。

4. 啟用 MastraPlatformExporter

下列範例示範如何將 MastraPlatformExporter 加入 Observability 設定：

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()],
      },
    },
  }),
})

請在 Observability 設定上設定 serviceName，而不是在 MastraPlatformExporter 本身設定。

請使用穩定的 serviceName 值。Studio 可依 Deployments → Service Name 篩選 Trace，因此一致的名稱能讓 Trace 更容易找到。

如需完整的 Observability 設定結構，請參閱 Observability 設定參考。

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

src/mastra/index.ts

new MastraPlatformExporter()

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

建議設定

如果也要在 Studio 中檢查本機 Trace，或將 Observability 資料保存至已設定的 Storage，請加入 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 平台。如果要將 telemetry 傳送至其他 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 中開啟專案，以檢查匯出的資料。

• 開啟 MASTRA_PROJECT_ID 所指定的專案，並選取 Open Studio。
• 在 Studio 中前往 Traces，檢查 Agent 與 Workflow Trace。
• 開啟 Filter 選單，並使用 Deployments → Service Name，找出特定應用程式或部署所產生的 Trace。
• 使用專案儀表板中的 Logs 頁面檢查匯出的 Log。

使用 Mastra Studio 部署時，請將 Deployment → Service Name 設為穩定的值，並使其與 Observability 設定中的 serviceName 保持一致。當多個服務或部署將資料傳送至相同專案時，這能讓你更容易在 Studio 中透過 Deployments → Service Name 篩選 Trace。

效能

資訊

MastraPlatformExporter 使用批次處理來最佳化網路用量。Event 會先進入 buffer，再分批傳送，在維持近乎即時可見性的同時減少額外負擔。

批次處理行為

• Event 會批次累積至 maxBatchSize（預設：1000）。
• 批次已滿或經過 maxBatchWaitMs（預設：5 秒）後就會送出。
• 失敗的批次會使用指數退避重試。
• 如果無法連線至 Mastra Studio，Exporter 會以降級方式繼續運作。

相關內容

• Tracing 總覽
• MastraStorageExporter