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

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

After (v1 with observability):

typescript

import { Mastra } from '@mastra/core'
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new DefaultExporter(), // Persists traces to storage for Mastra Studio
          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
      },
    },
  }),
})

This configuration includes 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:

bash

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

Key changes:

Install @mastra/observability package
Replace telemetry: with observability: new Observability()
Use explicit configs: with DefaultExporter, CloudExporter, 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

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

typescript

import { Mastra } from '@mastra/core'

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

After (v1 observability):

typescript

import { Mastra } from '@mastra/core'
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new DefaultExporter(), new CloudExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

Key changes:

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

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:

bash

npm install @mastra/observability@latest

diff

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

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.

diff

+ import {
+   Observability,
+   DefaultExporter,
+   CloudExporter,
+   SensitiveDataFilter,
+ } from '@mastra/observability';

  export const mastra = new Mastra({
-   observability: {
-     default: { enabled: true },
-   },
+   observability: new Observability({
+     configs: {
+       default: {
+         serviceName: 'mastra',
+         exporters: [new DefaultExporter(), new CloudExporter()],
+         spanOutputProcessors: [new SensitiveDataFilter()],
+       },
+     },
+   }),
  });

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.

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 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.

diff

  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:

javascript

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

And had to import it when starting your process:

bash

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:

typescript

// src/mastra/index.ts
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new DefaultExporter(), new CloudExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

Start your process normally without the --import flag:

bash

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

bash

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

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

bash

npm install @mastra/otel-exporter@latest

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

Tracing | v1 Migration Guide

Tracing

Migration paths

From OTEL-based Telemetry (0.x)

After (v1 with custom configuration)

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

Before (0.x)

After (v1)

Provider migration reference

Installation

Configuration property `processors` to `spanOutputProcessors`

Exporter method `exportEvent` to `exportTracingEvent`

OTEL-based `telemetry` configuration

`instrumentation.mjs` files