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

# Tracing

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

> **アップグレードすると Observability データの送信が停止:** `telemetry:` 設定を `observability:` に移行せずに Mastra パッケージを v1 へアップグレードすると、以前の設定は実行時に無視されます。サービスはエラーなく起動しますが、**Trace、Log、Metric はどこにも送信されません**。Mastra Cloud へデータを送信していた場合、Dashboard は空になります。
>
> Mastra パッケージを更新する変更と同時にこの移行を完了し、アップグレードが完了したと判断する前に [Mastra Studio](https://mastra.zisheng.pro/ja/docs/studio/observability) に Trace が表示されることを確認してください。以前 Mastra Cloud でホストしていた場合は、[Mastra Cloud 移行ガイド](https://mastra.zisheng.pro/ja/guides/migrations/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）：**

```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 が含まれます。すべての設定オプションについては、[Observability Tracing ドキュメント](https://mastra.zisheng.pro/ja/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. `MastraStorageExporter`、`MastraPlatformExporter`、`SensitiveDataFilter` を含む明示的な `configs:` を使用する
4. Export の型を文字列リテラル（`'otlp'`）から Exporter クラスのインスタンス（`new OtelExporter()`）へ変更する

利用可能なすべての Exporter については、[Exporter ドキュメント](https://mastra.zisheng.pro/ja/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、Processor を import する
3. `MastraStorageExporter`、`MastraPlatformExporter`、`SensitiveDataFilter` を含む明示的な `configs` を使用する

## 変更

### パッケージの import パス

Observability 機能は、専用の `@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 の設定

Observability Registry は、Plain Object ではなく、明示的な Config を含む `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（0.x）から移行する」セクションに従ってください。詳しい設定オプションについては、[Observability Tracing ドキュメント](https://mastra.zisheng.pro/ja/docs/observability/tracing/overview)を参照してください。

### カスタム Instrumentation ファイル

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

移行するには、組み込みの Exporter システムを使用するか、`ObservabilityExporter` インターフェースでカスタム Exporter を実装します。詳しくは、[Exporter ドキュメント](https://mastra.zisheng.pro/ja/docs/observability/integrations/overview)を参照してください。

### `instrumentation.mjs` ファイル

OpenTelemetry Instrumentation の初期化に `instrumentation.mjs` ファイルを使用していた場合（AWS Lambda などのデプロイ構成で一般的）、このファイルは不要になりました。新しい Observability システムは、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` フラグを指定せず、通常どおりプロセスを起動します。

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

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

## Provider 移行リファレンス

0.x で特定の Provider と OTEL ベースの Telemetry を使用していた場合、v1 では次のように設定します。

| Provider                                                  | Exporter          | ガイド                                                                                       | リファレンス                                                                                       |
| --------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Arize AX, Arize Phoenix                                   | **Arize**         | [ガイド](https://mastra.zisheng.pro/ja/docs/observability/integrations/exporters/arize)      | [リファレンス](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/arize)      |
| Braintrust                                                | **Braintrust**    | [ガイド](https://mastra.zisheng.pro/ja/docs/observability/integrations/exporters/braintrust) | [リファレンス](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/braintrust) |
| Langfuse                                                  | **Langfuse**      | [ガイド](https://mastra.zisheng.pro/ja/docs/observability/integrations/exporters/langfuse)   | [リファレンス](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/langfuse)   |
| LangSmith                                                 | **LangSmith**     | [ガイド](https://mastra.zisheng.pro/ja/docs/observability/integrations/exporters/langsmith)  | [リファレンス](https://mastra.zisheng.pro/ja/reference/observability/tracing/exporters/langsmith)  |
| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [ガイド](https://mastra.zisheng.pro/ja/docs/observability/integrations/exporters/otel)       | [リファレンス](https://mastra.zisheng.pro/ja/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/ja/docs/observability/integrations/exporters/otel)を参照）。