Tracing

Le système d’observabilité a été restructuré dans v1 avec un package dédié, @mastra/observability. Ce guide couvre deux chemins de migration selon la version depuis laquelle vous effectuez la mise à niveau.

Les données d’observabilité cessent d’être envoyées après la mise à niveau

Si vous mettez à niveau les packages Mastra vers v1 sans migrer votre configuration telemetry: vers observability:, l’ancienne configuration est ignorée à l’exécution. Votre service démarre proprement, sans erreur, mais aucune trace, aucun journal ni aucune métrique ne sera envoyé. Si vous envoyiez des données vers Mastra Cloud, le tableau de bord sera vide.

Effectuez cette migration dans le même changement que la mise à niveau de vos packages Mastra, et vérifiez que les traces apparaissent dans Mastra Studio avant de considérer la mise à niveau terminée. Si vous étiez auparavant hébergé sur Mastra Cloud, suivez également le guide de migration Mastra Cloud. La nouvelle plateforme requiert un nouveau token d’accès et un projet Studio avant que MastraPlatformExporter puisse y acheminer les données.

Changement de nom des exporters

MastraPlatformExporter, qui envoie les données vers la plateforme Mastra, remplace l’ancien CloudExporter, et MastraStorageExporter, qui persiste les données dans Mastra Storage, remplace l’ancien DefaultExporter. Les classes d’origine restent disponibles dans @mastra/observability et leur comportement est identique, mais elles sont obsolètes. Le nouveau code doit utiliser MastraPlatformExporter et MastraStorageExporter. Les imports existants de CloudExporter ou DefaultExporter continuent de fonctionner jusqu’à leur suppression dans une prochaine version majeure.

Chemins de migration

Depuis Telemetry basée sur OTEL (0.x)

Si vous utilisez l’ancienne configuration telemetry: dans Mastra, le système a été entièrement repensé.

Avant (0.x avec la télémétrie OTEL) :

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

Après (v1 avec l’observabilité) :

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

Cette configuration inclut MastraStorageExporter, MastraPlatformExporter et le processeur SensitiveDataFilter. Consultez la documentation du tracing d’observabilité pour connaître toutes les options de configuration.

Après (v1 avec une configuration personnalisée)

Si vous devez configurer des exporters spécifiques, comme OTLP, installez le package d’exporter et configurez-le :

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

Modifications principales :

1. Installez le package @mastra/observability
2. Remplacez telemetry: par observability: new Observability()
3. Utilisez des configs: explicites avec MastraStorageExporter, MastraPlatformExporter et SensitiveDataFilter
4. Les types d’export changent, passant de littéraux de chaîne, comme 'otlp', à des instances de classes d’exporter, comme new OtelExporter()

Consultez la documentation des exporters pour tous les exporters disponibles.

Depuis AI Tracing

Si vous avez déjà migré vers AI Tracing, le système intermédiaire, vous devez installer le nouveau package et utiliser la configuration explicite.

Avant (AI Tracing) :

import { Mastra } from '@mastra/core'

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

Après (observabilité 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(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

Modifications principales :

1. Installez le package @mastra/observability
2. Importez Observability, les exporters et les processeurs depuis @mastra/observability
3. Utilisez des configs explicites avec MastraStorageExporter, MastraPlatformExporter et SensitiveDataFilter

Modifications

Chemin d’import du package

La fonctionnalité d’observabilité a été déplacée vers un package dédié, @mastra/observability.

Pour migrer, installez le package et mettez à jour vos instructions d’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';

Configuration du registre

Le registre d’observabilité est désormais configuré avec une instance de classe Observability et des configs explicites, au lieu d’un objet simple.

Pour migrer, utilisez new Observability() avec des exporters et processeurs explicites.

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

Propriété de configuration processors remplacée par spanOutputProcessors

La propriété de configuration des processeurs de spans a été renommée de processors en spanOutputProcessors.

Pour migrer, renommez la propriété dans vos objets de configuration.

+ 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: [...],
        },
      },
    }),
  });

Méthode d’exporter exportEvent remplacée par exportTracingEvent

Si vous avez créé des exporters personnalisés, leur méthode a été renommée de exportEvent en exportTracingEvent.

Pour migrer, mettez à jour les implémentations de méthode dans les exporters personnalisés.

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

Éléments supprimés

Configuration telemetry basée sur OTEL

La configuration telemetry basée sur OTEL de la version 0.x a été supprimée. L’ancien système avec les propriétés serviceName, sampling.type et export.type n’est plus pris en charge.

Pour migrer, suivez la section « Depuis Telemetry basée sur OTEL » ci-dessus. Pour des options de configuration détaillées, consultez la documentation du tracing d’observabilité.

Fichiers d’instrumentation personnalisés

La détection automatique des fichiers d’instrumentation dans /mastra, avec les extensions .ts, .js ou .mjs, a été supprimée. L’instrumentation personnalisée n’est plus prise en charge au moyen de fichiers séparés.

Pour migrer, utilisez le système d’exporters intégré ou implémentez des exporters personnalisés avec l’interface ObservabilityExporter. Consultez la documentation des exporters pour plus de détails.

Fichiers instrumentation.mjs

Si vous utilisiez des fichiers instrumentation.mjs pour initialiser l’instrumentation OpenTelemetry, courante dans des configurations de déploiement comme AWS Lambda, ils ne sont plus nécessaires. Le nouveau système d’observabilité est configuré directement dans votre instance Mastra.

Avant (0.x)

Vous aviez besoin d’un fichier d’instrumentation :

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

Et vous deviez l’importer au démarrage du processus :

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

Après (v1)

Supprimez simplement le fichier instrumentation.mjs et configurez l’observabilité dans votre instance Mastra :

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

Démarrez normalement votre processus sans le flag --import :

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

Aucun fichier d’instrumentation séparé ni flag de démarrage spécial n’est requis.

Référence de migration des fournisseurs

Si vous utilisiez la télémétrie basée sur OTEL avec des fournisseurs spécifiques dans la version 0.x, voici comment les configurer dans v1 :

Fournisseur	Exporter	Guide	Référence
Arize AX, Arize Phoenix	Arize	Guide	Référence
Braintrust	Braintrust	Guide	Référence
Langfuse	Langfuse	Guide	Référence
LangSmith	LangSmith	Guide	Référence
Dash0, Laminar, New Relic, SigNoz, Traceloop, OTEL personnalisé	OpenTelemetry	Guide	Référence
LangWatch	<bientôt disponible>	-	-

Installation

Exporters dédiés (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

Exporter OpenTelemetry (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

Ajoutez le package de protocole requis pour votre fournisseur ; consultez le guide OTEL.