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

# Tracing

在 v1 中，可觀測性系統已重新設計，並使用專用的 `@mastra/observability` 套件。本指南會根據你目前升級的版本，介紹兩種遷移路徑。

> **升級後可觀測性資料會停止傳送:** 如果你將 Mastra 套件升級至 v1，但未將 `telemetry:` 配置遷移至 `observability:`，舊配置會在執行階段被忽略。你的服務會正常啟動且不會出現錯誤，但**任何 Trace、日誌或指標都不會傳送至任何地方**。如果你之前將資料傳送至 Mastra Cloud，儀表板將會變成空白。
>
> 請在升級 Mastra 套件的同一項變更中完成此遷移，並確認 [Mastra Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/observability) 中有顯示 Trace，才可視升級為完成。如果你之前託管於 Mastra Cloud，亦請按照 [Mastra Cloud 遷移指南](https://mastra.zisheng.pro/zh-HK/guides/migrations/mastra-cloud) 操作。新平台需要新的存取權杖和 Studio 項目，`MastraPlatformExporter` 才能將資料傳送至該平台。

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

## 遷移路徑

### 從以 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` processor。完整配置選項請參閱[可觀測性 tracing 文件](https://mastra.zisheng.pro/zh-HK/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. 將 `telemetry:` 替換為 `observability: new Observability()`
3. 使用明確的 `configs:`，當中包含 `MastraStorageExporter`、`MastraPlatformExporter` 及 `SensitiveDataFilter`
4. export 類型由字串字面值（`'otlp'`）改為 exporter 類別實例（`new OtelExporter()`）

所有可用的 exporter 請參閱 [exporter 文件](https://mastra.zisheng.pro/zh-HK/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. import `Observability`、exporter 及 processor，全部均來自 `@mastra/observability`
3. 使用明確的 `configs`，當中包含 `MastraStorageExporter`、`MastraPlatformExporter` 及 `SensitiveDataFilter`

## 已變更

### 套件 import 路徑

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

如要遷移，請安裝此套件並更新 import 陳述式：

**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 現在使用帶有明確 configs 的 `Observability` 類別實例進行配置，而非純物件。

如要遷移，請使用帶有明確 exporter 和 processor 的 `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 processor 的配置屬性已由 `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-HK/docs/observability/tracing/overview)。

### 自訂 instrumentation 檔案

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

如要遷移，請使用內置 exporter 系統，或透過 `ObservabilityExporter` 介面實作自訂 exporter。詳情請參閱 [exporter 文件](https://mastra.zisheng.pro/zh-HK/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
```

啟動程序時亦必須 import 該檔案：

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

#### 之後 (v1)

只需移除 `instrumentation.mjs` 檔案，並在 Mastra 實例中配置 observability：

```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` flag 的情況下正常啟動程序：

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

無需獨立的 instrumentation 檔案或特殊啟動 flag。

## Provider 遷移參考

如果你在 0.x 中使用以 OTEL 為基礎的 telemetry 及特定 Provider，可按以下方式在 v1 中配置：

| Provider                                                  | Exporter          | 指南                                                                                          | 參考資料                                                                                          |
| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Arize AX, Arize Phoenix                                   | **Arize**         | [指南](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/arize)      | [參考資料](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/arize)      |
| Braintrust                                                | **Braintrust**    | [指南](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/braintrust) | [參考資料](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/braintrust) |
| Langfuse                                                  | **Langfuse**      | [指南](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/langfuse)   | [參考資料](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/langfuse)   |
| LangSmith                                                 | **LangSmith**     | [指南](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/langsmith)  | [參考資料](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/langsmith)  |
| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [指南](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/otel)       | [參考資料](https://mastra.zisheng.pro/zh-HK/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-HK/docs/observability/integrations/exporters/otel)）。