> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Mastra 平台 exporter

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

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

> **自行託管或獨立的應用程式:** 如果你在自己的基礎設施上託管 Mastra 應用程式（而非 Mastra 平台），仍需要一個已部署的 Studio 項目，才能查看 traces、日誌及指標。`MastraPlatformExporter` 會將資料傳送至 Studio 項目，因此你必須先建立該項目才能使用它。
>
> 1. 如果你尚未有 Mastra 項目，請先[建立 Mastra 項目](https://mastra.zisheng.pro/zh-HK/guides/getting-started/quickstart)。
> 2. 使用 `mastra studio deploy` 將 [Studio 部署](https://mastra.zisheng.pro/zh-HK/docs/studio/deployment)至 Mastra 平台。
> 3. 按照[下方的快速開始步驟](#quickstart)建立存取權杖並找出項目 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. 建立存取權杖

執行以下命令：

```bash
mastra auth tokens create exporter-token
```

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

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

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

將權杖設定為環境變數：

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
```

### 2. 找出你的 `projectId`

執行以下命令：

```bash
mastra studio deploy list
```

輸出類似如下：

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

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

```text
<your-project-id>
```

將它設定為環境變數：

```bash
MASTRA_PROJECT_ID=<your-project-id>
```

### 3. 設定環境變數

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

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

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

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai
```

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

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
```

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

### 4. 啟用 `MastraPlatformExporter`

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

```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 更容易找到。

請參閱[可觀測性設定參考](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/configuration)，了解完整的可觀測性設定結構。

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

```ts
new MastraPlatformExporter()
```

設定 `MASTRA_PLATFORM_ACCESS_TOKEN` 和 `MASTRA_PROJECT_ID` 後，`MastraPlatformExporter` 會將資料傳送至你所設定的 Mastra 平台項目。如果你亦設定了 `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`，則會改為將資料傳送至該 collector。請參閱 [MastraPlatformExporter 參考](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/mastra-platform-exporter)，了解完整的設定選項清單。

## 建議設定

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

```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`。

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
```

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

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

## 在 Mastra Studio 中查看資料

啟用 `MastraPlatformExporter` 後，在 [Mastra Studio](https://projects.mastra.ai) 中開啟你的項目，以檢視已 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 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)
- [MastraStorageExporter](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/mastra-storage)