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.

Migration Paths

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 - quick start):

import { Mastra } from '@mastra/core';
import { Observability } from '@mastra/observability';

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

This minimal configuration automatically includes the DefaultExporter, CloudExporter, and SensitiveDataFilter processor. See the observability tracing documentation for full configuration options.

After (v1 with custom configuration):

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

npm install @mastra/otel-exporter@beta @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 default: { enabled: true } for quick setup, or configs: for custom configuration
Export types change from string literals ('otlp') to exporter class instances (new OtelExporter())

See the exporters documentation for all available exporters.

From AI Tracing

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

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 } from '@mastra/observability';

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

Key changes:

Install @mastra/observability package
Import Observability from @mastra/observability
Wrap configuration with new Observability()

Changed

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 install @mastra/observability@beta

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

Registry configuration

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

To migrate, wrap your configuration object with new Observability().

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

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

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`

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

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

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

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):

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):

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

// src/mastra/index.ts
import { Observability } from '@mastra/observability';

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

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

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

Dedicated exporters (Arize, Braintrust, Langfuse, LangSmith):

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

OpenTelemetry exporter (Dash0, Laminar, New Relic, SigNoz, Traceloop):

npm install @mastra/otel-exporter@beta

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

Migration Paths​

From OTEL-based Telemetry (0.x)​

From AI Tracing​

Changed​

Package import path​

Registry configuration​

Configuration property processors to spanOutputProcessors​

Exporter method exportEvent to exportTracingEvent​

Removed​

OTEL-based telemetry configuration​

Custom instrumentation files​

instrumentation.mjs files​

Provider Migration Reference​

Installation​