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

# Tracing

可觀測性系統已在 v1 中重整，並使用專用的 `@mastra/observability` 套件。本指南會依你升級前使用的版本，說明兩種遷移路徑。

> **升級後可觀測性資料停止傳送:** 如果將 Mastra 套件升級至 v1，卻沒有將 `telemetry:` 設定遷移至 `observability:`，執行階段會忽略舊設定。服務會正常啟動且不會發生錯誤，但**不會將任何 Trace、記錄或指標傳送至任何位置**。如果原本將資料傳送至 Mastra Cloud，儀表板會變成空白。
>
> 請在升級 Mastra 套件的同一次變更中完成此遷移，並確認 Trace 顯示在 [Mastra Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/observability) 中，再將升級視為完成。如果先前託管於 Mastra Cloud，還必須依照 [Mastra Cloud 遷移指南](https://mastra.zisheng.pro/zh-TW/guides/migrations/mastra-cloud)操作。新平台必須有新的存取權杖與 Studio 專案，`MastraPlatformExporter` 才能將資料傳送至該平台。

> **Exporter 重新命名:** `MastraPlatformExporter`（將資料傳送至 Mastra 平台）取代先前的 `CloudExporter`，而 `MastraStorageExporter`（將資料持久保存至 Mastra 儲存空間）則取代先前的 `DefaultExporter`。原始類別仍可從 `@mastra/observability` 取得，且行為完全相同，但已棄用。新程式碼應使用 `MastraPlatformExporter` 與 `MastraStorageExporter`。現有的 `CloudExporter` 或 `DefaultExporter` 匯入在未來主要版本移除前仍可繼續使用。

## 遷移路徑

### 從以 OTEL 為基礎的 Telemetry（0.x）遷移

如果你在 Mastra 中使用舊的 `telemetry:` 設定，該系統已完全重新設計。

**遷移前（使用 OTEL telemetry 的 0.x）：**

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  telemetry: {
    serviceName: 'my-app',
    enabled: true,
    sampling: {
      type: 'always_on',
    },
    export: {
      type: 'otlp',
      endpoint: 'http://localhost:4318',
    },
  },
})
```

**遷移後（使用 observability 的 v1）：**

```typescript
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(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (if MASTRA_PLATFORM_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
      },
    },
  }),
})
```

此設定包含 `MastraStorageExporter`、`MastraPlatformExporter` 與 `SensitiveDataFilter` 處理器。如需完整設定選項，請參閱[可觀測性 Tracing 文件](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)。

#### 遷移後（使用自訂設定的 v1）

如果需要設定特定 exporter（例如 OTLP），請安裝 exporter 套件並進行設定：

**npm**:

```bash
npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'my-app',
        sampling: { type: 'always' },
        exporters: [
          new OtelExporter({
            provider: {
              custom: {
                endpoint: 'http://localhost:4318/v1/traces',
                protocol: 'http/protobuf',
              },
            },
          }),
        ],
      },
    },
  }),
})
```

主要變更：

1. 安裝 `@mastra/observability` 套件
2. 使用 `observability: new Observability()` 取代 `telemetry:`
3. 使用明確的 `configs:`，並包含 `MastraStorageExporter`、`MastraPlatformExporter` 與 `SensitiveDataFilter`
4. 匯出型別從字串常值（`'otlp'`）變更為 exporter 類別執行個體（`new OtelExporter()`）

如需所有可用的 exporter，請參閱 [exporter 文件](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/overview)。

### 從 AI Tracing 遷移

如果你已升級至 AI tracing（中介系統），必須安裝新套件並使用明確設定。

**遷移前（AI tracing）：**

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  observability: {
    default: { enabled: true },
  },
})
```

**遷移後（v1 observability）：**

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

主要變更：

1. 安裝 `@mastra/observability` 套件
2. 從 `@mastra/observability` 匯入 `Observability`、exporter 與處理器
3. 使用明確的 `configs`，並包含 `MastraStorageExporter`、`MastraPlatformExporter` 與 `SensitiveDataFilter`

## 已變更

### 套件匯入路徑

可觀測性功能已移至專用的 `@mastra/observability` 套件。

遷移時，請安裝套件並更新匯入陳述式：

**npm**:

```bash
npm install @mastra/observability@latest
```

**pnpm**:

```bash
pnpm add @mastra/observability@latest
```

**Yarn**:

```bash
yarn add @mastra/observability@latest
```

**Bun**:

```bash
bun add @mastra/observability@latest
```

```diff
- import { Tracing } from '@mastra/core/observability';
+ import { Observability } from '@mastra/observability';
```

### Registry 設定

可觀測性 registry 現在會使用具有明確設定的 `Observability` 類別執行個體，而非純物件。

遷移時，請搭配明確的 exporter 與處理器使用 `new Observability()`。

```diff
+ import {
+   Observability,
+   MastraStorageExporter,
+   MastraPlatformExporter,
+   SensitiveDataFilter,
+ } from '@mastra/observability';

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

### 設定屬性 `processors` 改為 `spanOutputProcessors`

Span 處理器的設定屬性已從 `processors` 重新命名為 `spanOutputProcessors`。

遷移時，請在設定物件中重新命名此屬性。

```diff
+ import { SensitiveDataFilter } from '@mastra/observability';

  export const mastra = new Mastra({
    observability: new Observability({
      configs: {
        production: {
          serviceName: 'my-app',
-         processors: [new SensitiveDataFilter()],
+         spanOutputProcessors: [new SensitiveDataFilter()],
          exporters: [...],
        },
      },
    }),
  });
```

### Exporter 方法 `exportEvent` 改為 `exportTracingEvent`

如果你建置了自訂 exporter，exporter 方法已從 `exportEvent` 重新命名為 `exportTracingEvent`。

遷移時，請更新自訂 exporter 中的方法實作。

```diff
export class MyExporter implements ObservabilityExporter {
-   exportEvent(event: TracingEvent): void {
+   exportTracingEvent(event: TracingEvent): void {
      // export logic
    }
  }
```

## 已移除

### 以 OTEL 為基礎的 `telemetry` 設定

0.x 中以 OTEL 為基礎的 `telemetry` 設定已移除。不再支援具有 `serviceName`、`sampling.type` 與 `export.type` 屬性的舊系統。

遷移時，請依照上方「從以 OTEL 為基礎的 Telemetry 遷移」區段操作。如需詳細設定選項，請參閱[可觀測性 Tracing 文件](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)。

### 自訂 instrumentation 檔案

已移除自動偵測 `/mastra` 中 instrumentation 檔案（副檔名為 `.ts`、`.js` 或 `.mjs`）的功能。不再支援透過個別檔案進行自訂 instrumentation。

遷移時，請使用內建 exporter 系統，或使用 `ObservabilityExporter` 介面實作自訂 exporter。詳情請參閱 [exporter 文件](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/overview)。

### `instrumentation.mjs` 檔案

如果原本使用 `instrumentation.mjs` 檔案初始化 OpenTelemetry instrumentation（常見於 AWS Lambda 等部署環境），現在已不再需要這些檔案。新的可觀測性系統會直接在 Mastra 執行個體中設定。

#### 遷移前（0.x）

原本需要 instrumentation 檔案：

```javascript
// instrumentation.mjs
import { NodeSDK } from '@opentelemetry/sdk-node'
// ... OTEL setup
```

而且啟動處理程序時必須匯入該檔案：

```bash
node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs
```

#### 遷移後（v1）

只要移除 `instrumentation.mjs` 檔案，並在 Mastra 執行個體中設定可觀測性：

```typescript
// src/mastra/index.ts
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()],
      },
    },
  }),
})
```

正常啟動處理程序即可，不需要 `--import` 旗標：

```bash
node --env-file=".env" .mastra/output/index.mjs
```

不需要個別的 instrumentation 檔案或特殊啟動旗標。

## Provider 遷移參考資料

如果你在 0.x 中使用搭配特定 Provider、以 OTEL 為基礎的遙測，以下是在 v1 中的設定方式：

| Provider                                                  | Exporter          | 指南                                                                                          | 參考文件                                                                                          |
| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Arize AX, Arize Phoenix                                   | **Arize**         | [指南](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/arize)      | [參考文件](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/arize)      |
| Braintrust                                                | **Braintrust**    | [指南](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/braintrust) | [參考文件](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/braintrust) |
| Langfuse                                                  | **Langfuse**      | [指南](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/langfuse)   | [參考文件](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/langfuse)   |
| LangSmith                                                 | **LangSmith**     | [指南](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/langsmith)  | [參考文件](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/langsmith)  |
| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [指南](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/otel)       | [參考文件](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/otel)       |
| LangWatch                                                 | <即將推出>            | -                                                                                           | -                                                                                             |

### 安裝

**專用 exporter**（Arize、Braintrust、Langfuse、LangSmith）：

**npm**:

```bash
npm install @mastra/[exporter-name]-exporter
```

**pnpm**:

```bash
pnpm add @mastra/[exporter-name]-exporter
```

**Yarn**:

```bash
yarn add @mastra/[exporter-name]-exporter
```

**Bun**:

```bash
bun add @mastra/[exporter-name]-exporter
```

**OpenTelemetry exporter**（Dash0、Laminar、New Relic、SigNoz、Traceloop）：

**npm**:

```bash
npm install @mastra/otel-exporter@latest
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest
```

再加上 Provider 所需的通訊協定套件（請參閱 [OTEL 指南](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/otel)）。