Tracing

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

升級後可觀測性資料停止傳送

如果將 Mastra 套件升級至 v1，卻沒有將 telemetry: 設定遷移至 observability:，執行階段會忽略舊設定。服務會正常啟動且不會發生錯誤，但不會將任何 Trace、記錄或指標傳送至任何位置。如果原本將資料傳送至 Mastra Cloud，儀表板會變成空白。

請在升級 Mastra 套件的同一次變更中完成此遷移，並確認 Trace 顯示在 Mastra Studio 中，再將升級視為完成。如果先前託管於 Mastra Cloud，還必須依照 Mastra Cloud 遷移指南操作。新平台必須有新的存取權杖與 Studio 專案，MastraPlatformExporter 才能將資料傳送至該平台。

Exporter 重新命名

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

遷移路徑
「遷移路徑」的直接連結

從以 OTEL 為基礎的 Telemetry（0.x）遷移
「從以 OTEL 為基礎的 Telemetry（0.x）遷移」的直接連結

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

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

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）：

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 文件。

遷移後（使用自訂設定的 v1）
「遷移後（使用自訂設定的 v1）」的直接連結

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

npm
pnpm
Yarn
Bun

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

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

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

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

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

主要變更：

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

如需所有可用的 exporter，請參閱 exporter 文件。

從 AI Tracing 遷移
「從 AI Tracing 遷移」的直接連結

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

遷移前（AI tracing）：

import { Mastra } from '@mastra/core'

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

遷移後（v1 observability）：

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

主要變更：

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

已變更
「已變更」的直接連結

套件匯入路徑
「套件匯入路徑」的直接連結

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

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

npm
pnpm
Yarn
Bun

npm install @mastra/observability@latest

pnpm add @mastra/observability@latest

yarn add @mastra/observability@latest

bun add @mastra/observability@latest

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

Registry 設定
「Registry 設定」的直接連結

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

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

+ 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`
「configuration-property-processors-to-spanoutputprocessors」的直接連結

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

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

+ 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-method-exportevent-to-exporttracingevent」的直接連結

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

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

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

已移除
「已移除」的直接連結

以 OTEL 為基礎的 `telemetry` 設定
「otel-based-telemetry-configuration」的直接連結

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

遷移時，請依照上方「從以 OTEL 為基礎的 Telemetry 遷移」區段操作。如需詳細設定選項，請參閱可觀測性 Tracing 文件。

自訂 instrumentation 檔案
「自訂 instrumentation 檔案」的直接連結

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

遷移時，請使用內建 exporter 系統，或使用 ObservabilityExporter 介面實作自訂 exporter。詳情請參閱 exporter 文件。

`instrumentation.mjs` 檔案
「instrumentationmjs-files」的直接連結

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

遷移前（0.x）
「遷移前（0.x）」的直接連結

原本需要 instrumentation 檔案：

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

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

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

遷移後（v1）
「遷移後（v1）」的直接連結

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

// 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 旗標：

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

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

Provider 遷移參考資料
「Provider 遷移參考資料」的直接連結

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

Provider	Exporter	指南	參考文件
Arize AX, Arize Phoenix	Arize	指南	參考文件
Braintrust	Braintrust	指南	參考文件
Langfuse	Langfuse	指南	參考文件
LangSmith	LangSmith	指南	參考文件
Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL	OpenTelemetry	指南	參考文件
LangWatch	<即將推出>	-	-

安裝
「安裝」的直接連結

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

npm
pnpm
Yarn
Bun

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

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

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

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

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

npm
pnpm
Yarn
Bun

npm install @mastra/otel-exporter@latest

pnpm add @mastra/otel-exporter@latest

yarn add @mastra/otel-exporter@latest

bun add @mastra/otel-exporter@latest

再加上 Provider 所需的通訊協定套件（請參閱 OTEL 指南）。

遷移路徑「遷移路徑」的直接連結

從以 OTEL 為基礎的 Telemetry（0.x）遷移「從以 OTEL 為基礎的 Telemetry（0.x）遷移」的直接連結

遷移後（使用自訂設定的 v1）「遷移後（使用自訂設定的 v1）」的直接連結

從 AI Tracing 遷移「從 AI Tracing 遷移」的直接連結

已變更「已變更」的直接連結

套件匯入路徑「套件匯入路徑」的直接連結

Registry 設定「Registry 設定」的直接連結

設定屬性 processors 改為 spanOutputProcessors「configuration-property-processors-to-spanoutputprocessors」的直接連結

Exporter 方法 exportEvent 改為 exportTracingEvent「exporter-method-exportevent-to-exporttracingevent」的直接連結

已移除「已移除」的直接連結

以 OTEL 為基礎的 telemetry 設定「otel-based-telemetry-configuration」的直接連結

自訂 instrumentation 檔案「自訂 instrumentation 檔案」的直接連結

instrumentation.mjs 檔案「instrumentationmjs-files」的直接連結

遷移前（0.x）「遷移前（0.x）」的直接連結

遷移後（v1）「遷移後（v1）」的直接連結

Provider 遷移參考資料「Provider 遷移參考資料」的直接連結

安裝「安裝」的直接連結