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

# 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 專案](https://mastra.zisheng.pro/zh-TW/guides/getting-started/quickstart)。
> 2. 使用 `mastra studio deploy` 將 [Studio 部署](https://mastra.zisheng.pro/zh-TW/docs/studio/deployment)至 Mastra 平台。
> 3. 依照[下方快速入門步驟](#quickstart)建立 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

執行下列命令：

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

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

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

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

將 token 設為環境變數：

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

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

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

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

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

### 4. 啟用 `MastraPlatformExporter`

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

```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 設定參考](https://mastra.zisheng.pro/zh-TW/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-TW/reference/observability/tracing/exporters/mastra-platform-exporter)。

## 建議設定

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

- 開啟 `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 總覽](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)
- [MastraStorageExporter](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/mastra-storage)