Exportateur Mastra Platform

MastraPlatformExporter envoie les traces, journaux, métriques, scores et retours à Mastra Platform. Utilisez-le pour router les données d’observabilité de n’importe quelle application Mastra vers un projet hébergé sur Mastra Platform.

remarque

MastraPlatformExporter s’appelait auparavant CloudExporter. La classe CloudExporter d’origine est toujours exportée depuis @mastra/observability pour assurer la rétrocompatibilité, mais elle est obsolète. Le nouveau code doit utiliser MastraPlatformExporter.

Applications auto-hébergées ou autonomes

Si vous hébergez votre application Mastra sur votre propre infrastructure, et non sur Mastra Platform, vous avez toujours besoin d’un projet Studio déployé pour consulter les traces, journaux et métriques. MastraPlatformExporter envoie les données à un projet Studio ; celui-ci doit donc exister avant que vous puissiez l’utiliser.

1. Créez un projet Mastra si vous n’en avez pas encore.
2. Déployez Studio sur Mastra Platform avec mastra studio deploy.
3. Suivez les étapes de démarrage rapide ci-dessous pour créer un token d’accès et trouver l’identifiant de votre projet.

Compatibilité des versions

• MastraPlatformExporter est disponible à partir de @mastra/observability@1.12.0. Entre 1.8.0 et 1.11.x, le même exportateur est disponible uniquement sous le nom CloudExporter. La signature du constructeur et les variables d’environnement sont identiques.
• De @mastra/observability@1.8.0 à 1.9.1, définissez MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai en plus de MASTRA_PLATFORM_ACCESS_TOKEN et MASTRA_PROJECT_ID.
• À partir de @mastra/observability@1.9.2, l’exportateur utilise par défaut https://observability.mastra.ai. MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT n’est donc nécessaire que si vous souhaitez envoyer la télémétrie à un autre collecteur.

Démarrage rapide

Pour connecter MastraPlatformExporter, créez un token d’accès, trouvez le projectId de destination et ajoutez l’exportateur à votre configuration d’observabilité.

1. Créer un token d’accès

Exécutez la commande suivante :

mastra auth tokens create exporter-token

Cette commande affiche un token secret que vous pouvez utiliser comme MASTRA_PLATFORM_ACCESS_TOKEN.

Si vous possédez déjà un token d’accès, copiez plutôt la valeur Observabilité depuis Mastra Platform. Vous la trouverez à l’un des emplacements suivants :

• Sur la page Projets, ouvrez la liste des projets et recherchez la ligne Observabilité sur la carte du projet.
• Sur la page Vue d’ensemble du projet, recherchez la ligne Observabilité directement sous l’URL de déploiement.

Définissez le token comme variable d’environnement :

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>

2. Trouver votre projectId

Exécutez la commande suivante :

mastra studio deploy list

La sortie ressemble à ceci :

✅ <your-project-name> (<your-project-id>)
   Latest:   00000000-0000-0000-0000-000000000000 — running
   URL:      https://260407.studio.mastra.cloud

Dans cette sortie, la valeur entre parenthèses est le projectId :

<your-project-id>

Définissez-le comme variable d’environnement :

.env

MASTRA_PROJECT_ID=<your-project-id>

3. Définir vos variables d’environnement

Définissez les deux valeurs dans votre environnement afin que MastraPlatformExporter puisse s’authentifier et router la télémétrie vers le bon projet :

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
MASTRA_PROJECT_ID=<your-project-id>

Si vous utilisez une version comprise entre @mastra/observability@1.8.0 et 1.9.1, définissez également explicitement le collecteur Mastra Platform :

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai

Si vous souhaitez envoyer la télémétrie ailleurs que vers Mastra Platform, définissez également MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT. Transmettez soit une origine de base, soit une URL complète de publication des traces se terminant par /spans/publish.

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

Lorsque vous transmettez une origine de base, MastraPlatformExporter déduit automatiquement les URL de publication correspondantes pour les traces, journaux, métriques, scores et retours.

4. Activer MastraPlatformExporter

L’exemple suivant montre comment ajouter MastraPlatformExporter à votre configuration d’observabilité :

src/mastra/index.ts

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'api-server',
        exporters: [new MastraPlatformExporter()],
      },
    },
  }),
})

Définissez serviceName dans la configuration d’observabilité, et non dans MastraPlatformExporter lui-même.

Utilisez une valeur serviceName stable. Dans Studio, vous pouvez filtrer les traces par Déploiements → Nom du service ; un nom cohérent facilite donc leur recherche.

Consultez la référence de la configuration d’observabilité pour découvrir la structure complète de cette configuration.

Si vous préférez, vous pouvez vous appuyer entièrement sur les variables d’environnement :

src/mastra/index.ts

new MastraPlatformExporter()

Lorsque MASTRA_PLATFORM_ACCESS_TOKEN et MASTRA_PROJECT_ID sont définis, MastraPlatformExporter envoie les données au projet Mastra Platform que vous avez configuré. Si vous définissez également MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT, il les envoie à ce collecteur à la place. Consultez la référence de MastraPlatformExporter pour obtenir la liste complète des options de configuration.

Configuration recommandée

Incluez MastraStorageExporter si vous souhaitez également inspecter les traces locales dans Studio ou conserver les données d’observabilité dans le stockage configuré.

src/mastra/index.ts

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

Configuration complète

MastraPlatformExporter cible Mastra Platform par défaut. Si vous souhaitez envoyer la télémétrie à un autre collecteur, définissez MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT dans votre environnement ou transmettez endpoint dans le code.

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

L’exemple suivant montre comment remplacer l’endpoint du collecteur et le comportement de traitement par lots dans le code :

src/mastra/index.ts

new MastraPlatformExporter({
  endpoint: 'https://collector.example.com',
  maxBatchSize: 1000,
  maxBatchWaitMs: 5000,
  logLevel: 'info',
})

Consulter les données dans Mastra Studio

Après avoir activé MastraPlatformExporter, ouvrez votre projet dans Mastra Studio pour inspecter les données exportées.

• Ouvrez le projet auquel vous avez associé MASTRA_PROJECT_ID, puis sélectionnez Ouvrir Studio.
• Dans Studio, accédez à Traces pour inspecter les traces des agents et des workflows.
• Ouvrez le menu de filtrage et utilisez Déploiements → Nom du service pour isoler les traces d’une application ou d’un déploiement précis.
• Utilisez la page Journaux du tableau de bord du projet pour inspecter les journaux exportés.

Lorsque vous effectuez un déploiement avec Mastra Studio, définissez Déploiement → Nom du service sur une valeur stable et veillez à ce qu’elle corresponde au serviceName de votre configuration d’observabilité. Il devient ainsi plus facile de filtrer les traces dans Studio au moyen de Déploiements → Nom du service lorsque plusieurs services ou déploiements envoient des données au même projet.

Performances

info

MastraPlatformExporter utilise le traitement par lots afin d’optimiser l’utilisation du réseau. Les événements sont mis en mémoire tampon et envoyés par lots, ce qui réduit la surcharge tout en maintenant une visibilité presque en temps réel.

Comportement du traitement par lots

• Les événements sont regroupés par lots jusqu’à maxBatchSize (valeur par défaut : 1000).
• Les lots sont envoyés lorsqu’ils sont pleins ou après maxBatchWaitMs (valeur par défaut : 5 secondes).
• Les lots ayant échoué sont réessayés avec un délai exponentiel.
• L’exportateur continue de fonctionner de manière dégradée si Mastra Studio est inaccessible.

Ressources associées

• Vue d’ensemble du traçage
• MastraStorageExporter