Tracing

v1 では、専用の @mastra/observability パッケージを使用するよう Observability システムが再構成されました。このガイドでは、アップグレード元のバージョンに応じた 2 つの移行方法を説明します。

アップグレードすると Observability データの送信が停止

telemetry: 設定を observability: に移行せずに Mastra パッケージを v1 へアップグレードすると、以前の設定は実行時に無視されます。サービスはエラーなく起動しますが、Trace、Log、Metric はどこにも送信されません。Mastra Cloud へデータを送信していた場合、Dashboard は空になります。

Mastra パッケージを更新する変更と同時にこの移行を完了し、アップグレードが完了したと判断する前に Mastra Studio に Trace が表示されることを確認してください。以前 Mastra Cloud でホストしていた場合は、Mastra Cloud 移行ガイドにも従ってください。新しい Platform へ MastraPlatformExporter でデータを送信するには、新しいアクセストークンと Studio プロジェクトが必要です。

Exporter の改名

以前の CloudExporter は MastraPlatformExporter（Mastra platform へデータを送信）に、以前の DefaultExporter は MastraStorageExporter（Mastra Storage にデータを永続化）に置き換えられました。元のクラスも @mastra/observability から引き続き利用でき、動作は同一ですが、非推奨です。新しいコードでは MastraPlatformExporter と MastraStorageExporter を使用してください。既存の CloudExporter または DefaultExporter の import は、今後のメジャーバージョンで削除されるまで動作します。

移行方法

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 が含まれます。すべての設定オプションについては、Observability Tracing ドキュメントを参照してください。

変更後（カスタム設定を使用する v1）

特定の Exporter（OTLP など）を設定する必要がある場合は、Exporter パッケージをインストールして設定します。

npm

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

pnpm

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

Yarn

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

Bun

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

主な変更点：

1. @mastra/observability パッケージをインストールする
2. telemetry: を observability: new Observability() に置き換える
3. MastraStorageExporter、MastraPlatformExporter、SensitiveDataFilter を含む明示的な configs: を使用する
4. Export の型を文字列リテラル（'otlp'）から Exporter クラスのインスタンス（new OtelExporter()）へ変更する

利用可能なすべての Exporter については、Exporter ドキュメントを参照してください。

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

主な変更点：

1. @mastra/observability パッケージをインストールする
2. @mastra/observability から Observability、Exporter、Processor を import する
3. MastraStorageExporter、MastraPlatformExporter、SensitiveDataFilter を含む明示的な configs を使用する

変更

パッケージの import パス

Observability 機能は、専用の @mastra/observability パッケージへ移動しました。

移行するには、パッケージをインストールして import 文を更新します。

npm

npm install @mastra/observability@latest

pnpm

pnpm add @mastra/observability@latest

Yarn

yarn add @mastra/observability@latest

Bun

bun add @mastra/observability@latest

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

Registry の設定

Observability Registry は、Plain Object ではなく、明示的な Config を含む 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 へ変更

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 を作成している場合は、Exporter メソッドが exportEvent から exportTracingEvent に改名されました。

移行するには、カスタム Exporter のメソッド実装を更新します。

  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（0.x）から移行する」セクションに従ってください。詳しい設定オプションについては、Observability Tracing ドキュメントを参照してください。

カスタム Instrumentation ファイル

/mastra 内の Instrumentation ファイル（拡張子 .ts、.js、.mjs）の自動検出が削除されました。別ファイルによるカスタム Instrumentation はサポートされなくなりました。

移行するには、組み込みの Exporter システムを使用するか、ObservabilityExporter インターフェースでカスタム Exporter を実装します。詳しくは、Exporter ドキュメントを参照してください。

instrumentation.mjs ファイル

OpenTelemetry Instrumentation の初期化に instrumentation.mjs ファイルを使用していた場合（AWS Lambda などのデプロイ構成で一般的）、このファイルは不要になりました。新しい Observability システムは、Mastra インスタンスで直接設定します。

変更前（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）

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 フラグを指定せず、通常どおりプロセスを起動します。

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

個別の Instrumentation ファイルや特殊な起動フラグは不要です。

Provider 移行リファレンス

0.x で特定の Provider と OTEL ベースの Telemetry を使用していた場合、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

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

pnpm

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

Yarn

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

Bun

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

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

npm

npm install @mastra/otel-exporter@latest

pnpm

pnpm add @mastra/otel-exporter@latest

Yarn

yarn add @mastra/otel-exporter@latest

Bun

bun add @mastra/otel-exporter@latest

加えて、Provider に必要なプロトコルパッケージをインストールします（OTEL ガイドを参照）。