Tracing

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

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

如果你將 Mastra 套件升級至 v1，但未將 telemetry: 配置遷移至 observability:，舊配置會在執行階段被忽略。你的服務會正常啟動且不會出現錯誤，但任何 Trace、日誌或指標都不會傳送至任何地方。如果你之前將資料傳送至 Mastra Cloud，儀表板將會變成空白。

請在升級 Mastra 套件的同一項變更中完成此遷移，並確認 Mastra Studio 中有顯示 Trace，才可視升級為完成。如果你之前託管於 Mastra Cloud，亦請按照 Mastra Cloud 遷移指南操作。新平台需要新的存取權杖和 Studio 項目，MastraPlatformExporter 才能將資料傳送至該平台。

Exporter 重新命名

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

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

從以 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 processor。完整配置選項請參閱可觀測性 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 套件
將 telemetry: 替換為 observability: new Observability()
使用明確的 configs:，當中包含 MastraStorageExporter、MastraPlatformExporter 及 SensitiveDataFilter
export 類型由字串字面值（'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 套件
import Observability、exporter 及 processor，全部均來自 @mastra/observability
使用明確的 configs，當中包含 MastraStorageExporter、MastraPlatformExporter 及 SensitiveDataFilter

已變更
已變更的直接連結

套件 import 路徑
套件 import 路徑的直接連結

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

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

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

如要遷移，請使用帶有明確 exporter 和 processor 的 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 processor 的配置屬性已由 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

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

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

之後 (v1)
之後 (v1) 的直接連結

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

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

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

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

Provider 遷移參考
Provider 遷移參考的直接連結

如果你在 0.x 中使用以 OTEL 為基礎的 telemetry 及特定 Provider，可按以下方式在 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 遷移 的直接連結

已變更已變更 的直接連結

套件 import 路徑套件 import 路徑 的直接連結

Registry 配置Registry 配置 的直接連結

配置屬性由 processors 改為 spanOutputProcessorsconfiguration-property-processors-to-spanoutputprocessors 的直接連結

Exporter 方法由 exportEvent 改為 exportTracingEventexporter-method-exportevent-to-exporttracingevent 的直接連結

已移除已移除 的直接連結

以 OTEL 為基礎的 telemetry 配置otel-based-telemetry-configuration 的直接連結

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

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

之前 (0.x)之前 (0.x) 的直接連結

之後 (v1)之後 (v1) 的直接連結

Provider 遷移參考Provider 遷移參考 的直接連結

安裝安裝 的直接連結