Tracing

The observability system has been restructured in v1 with a dedicated @mastra/observability package. This guide covers two migration paths depending on which version you're upgrading from.

Observability data stops flowing on upgrade

If you upgrade Mastra packages to v1 without migrating your telemetry: config to observability:, the old config is ignored at runtime. Your service will start cleanly with no error, but no traces, logs, or metrics will be sent anywhere. If you were sending data to Mastra Cloud, the dashboard will go empty.

Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in Mastra Studio before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the Mastra Cloud migration guide — the new platform requires a new access token and a Studio project before MastraPlatformExporter can route data to it.

Exporter rename

MastraPlatformExporter (sends data to Mastra platform) replaces the previous CloudExporter, and MastraStorageExporter (persists data to Mastra Storage) replaces the previous DefaultExporter. The original classes still ship from @mastra/observability and behave identically, but they are deprecated. New code should use MastraPlatformExporter and MastraStorageExporter; existing imports of CloudExporter/DefaultExporter continue to work until they are removed in a future major version.

Migration paths
Direct link to Migration paths

From OTEL-based Telemetry (0.x)
Direct link to From OTEL-based Telemetry (0.x)

If you're using the old telemetry: configuration in Mastra, the system has been completely redesigned.

Before (0.x with OTEL telemetry):

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

After (v1 with 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(), // 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
        ],
      },
    },
  }),
})

This configuration includes MastraStorageExporter, MastraPlatformExporter, and SensitiveDataFilter processor. See the observability tracing documentation for full configuration options.

After (v1 with custom configuration)
Direct link to After (v1 with custom configuration)

If you need to configure specific exporters (like OTLP), install the exporter package and configure it:

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

Key changes:

Install @mastra/observability package
Replace telemetry: with observability: new Observability()
Use explicit configs: with MastraStorageExporter, MastraPlatformExporter, and SensitiveDataFilter
Export types change from string literals ('otlp') to exporter class instances (new OtelExporter())

See the exporters documentation for all available exporters.

From AI Tracing
Direct link to From AI Tracing

If you already upgraded to AI tracing (the intermediate system), you need to install the new package and use the explicit configuration.

Before (AI tracing):

import { Mastra } from '@mastra/core'

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

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

Key changes:

Install @mastra/observability package
Import Observability, exporters, and processors from @mastra/observability
Use explicit configs with MastraStorageExporter, MastraPlatformExporter, and SensitiveDataFilter

Changed
Direct link to Changed

Package import path
Direct link to Package import path

The observability functionality has moved to a dedicated @mastra/observability package.

To migrate, install the package and update your import statements:

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 configuration
Direct link to Registry configuration

The observability registry is now configured using an Observability class instance with explicit configs instead of a plain object.

To migrate, use new Observability() with explicit exporters and processors.

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

Configuration property `processors` to `spanOutputProcessors`
Direct link to configuration-property-processors-to-spanoutputprocessors

The configuration property for span processors has been renamed from processors to spanOutputProcessors.

To migrate, rename the property in your configuration objects.

+ 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 method `exportEvent` to `exportTracingEvent`
Direct link to exporter-method-exportevent-to-exporttracingevent

If you built custom exporters, the exporter method has been renamed from exportEvent to exportTracingEvent.

To migrate, update method implementations in custom exporters.

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

Removed
Direct link to Removed

OTEL-based `telemetry` configuration
Direct link to otel-based-telemetry-configuration

The OTEL-based telemetry configuration from 0.x has been removed. The old system with serviceName, sampling.type, and export.type properties is no longer supported.

To migrate, follow the "From OTEL-based Telemetry" section above. For detailed configuration options, see the observability tracing documentation.

Custom instrumentation files
Direct link to Custom instrumentation files

The automatic detection of instrumentation files in /mastra (with .ts, .js, or .mjs extensions) has been removed. Custom instrumentation is no longer supported through separate files.

To migrate, use the built-in exporter system or implement custom exporters using the ObservabilityExporter interface. See the exporters documentation for details.

`instrumentation.mjs` files
Direct link to instrumentationmjs-files

If you were using instrumentation.mjs files to initialize OpenTelemetry instrumentation (common in deployment setups like AWS Lambda), these are no longer needed. The new observability system is configured directly in your Mastra instance.

Before (0.x)
Direct link to Before (0.x)

You needed an instrumentation file:

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

And had to import it when starting your process:

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

After (v1)
Direct link to After (v1)

Simply remove the instrumentation.mjs file and configure observability in your Mastra instance:

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

Start your process normally without the --import flag:

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

No separate instrumentation files or special startup flags required.

Provider migration reference
Direct link to Provider migration reference

If you were using OTEL-based telemetry with specific providers in 0.x, here's how to configure them in v1:

Provider	Exporter	Guide	Reference
Arize AX, Arize Phoenix	Arize	Guide	Reference
Braintrust	Braintrust	Guide	Reference
Langfuse	Langfuse	Guide	Reference
LangSmith	LangSmith	Guide	Reference
Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL	OpenTelemetry	Guide	Reference
LangWatch	<coming soon>	-	-

Installation
Direct link to Installation

Dedicated exporters (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

Plus the required protocol package for your provider (see OTEL guide).

Migration pathsDirect link to Migration paths

From OTEL-based Telemetry (0.x)Direct link to From OTEL-based Telemetry (0.x)

After (v1 with custom configuration)Direct link to After (v1 with custom configuration)

From AI TracingDirect link to From AI Tracing

ChangedDirect link to Changed

Package import pathDirect link to Package import path

Registry configurationDirect link to Registry configuration

Configuration property processors to spanOutputProcessorsDirect link to configuration-property-processors-to-spanoutputprocessors

Exporter method exportEvent to exportTracingEventDirect link to exporter-method-exportevent-to-exporttracingevent

RemovedDirect link to Removed

OTEL-based telemetry configurationDirect link to otel-based-telemetry-configuration

Custom instrumentation filesDirect link to Custom instrumentation files

instrumentation.mjs filesDirect link to instrumentationmjs-files

Before (0.x)Direct link to Before (0.x)

After (v1)Direct link to After (v1)

Provider migration referenceDirect link to Provider migration reference

InstallationDirect link to Installation