Exportateur Mastra Storage

MastraStorageExporter conserve les traces dans le backend de stockage configuré, ce qui les rend accessibles dans Studio. Il ne nécessite aucun service externe.

remarque

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

Observabilité en production

Les données d’observabilité peuvent rapidement saturer les bases de données généralistes en production. Pour les applications à fort trafic, routez le domaine de stockage de l’observabilité vers ClickHouse au moyen du stockage composite. Consultez les recommandations pour la production pour plus de détails.

Configuration

Prérequis

1. Backend de stockage : configurez un fournisseur de stockage, par exemple libSQL ou PostgreSQL
2. Studio : installez-le pour consulter les traces localement

Configuration de base

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db', // Required for trace persistence
  }),
  observability: new Observability({
    configs: {
      local: {
        serviceName: 'my-service',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})

Configuration recommandée

Incluez MastraStorageExporter dans votre configuration d’observabilité :

import { Mastra } from '@mastra/core'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (requires MASTRA_PLATFORM_ACCESS_TOKEN)
        ],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

Studio

Accédez à vos traces dans Studio :

1. Démarrez Studio
2. Accédez à Observabilité
3. Filtrez et recherchez vos traces locales
4. Inspectez les informations détaillées des spans

Stratégies de traçage

MastraStorageExporter sélectionne automatiquement la stratégie de traçage optimale selon votre fournisseur de stockage. Vous pouvez également remplacer cette sélection si nécessaire.

Stratégies disponibles

Stratégie	Description	Cas d’utilisation
realtime	Traite immédiatement chaque événement	Développement, débogage, faible trafic
batch-with-updates	Met les événements en mémoire tampon et les écrit par lots avec une prise en charge complète du cycle de vie	Production à faible volume
insert-only	Traite uniquement les spans terminés et ignore les mises à jour	Production à fort volume

Configuration de la stratégie

new MastraStorageExporter({
  strategy: 'auto', // Default - let storage provider decide
  // or explicitly set:
  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only'

  // Batching configuration (applies to both batch-with-updates and insert-only)
  maxBatchSize: 1000, // Max spans per batch
  maxBatchWaitMs: 5000, // Max wait before flushing
  maxBufferSize: 10000, // Max spans to buffer
})

Prise en charge des fournisseurs de stockage

Les fournisseurs de stockage prennent en charge différentes stratégies de traçage. Certains prennent en charge l’observabilité pour les charges de production, tandis que d’autres sont principalement destinés au développement local.

Si vous définissez la stratégie sur 'auto', MastraStorageExporter sélectionne automatiquement la stratégie optimale pour le fournisseur de stockage. Si vous définissez explicitement une stratégie que le fournisseur ne prend pas en charge, l’exportateur journalise un avertissement et se rabat sur la stratégie préférée du fournisseur.

Fournisseurs prenant en charge l’observabilité

Fournisseur de stockage	Stratégie préférée	Stratégies prises en charge	Utilisation recommandée
ClickHouse	insert-only	insert-only	Production à fort volume
PostgreSQL	batch-with-updates	batch-with-updates, insert-only	Production à faible volume
MSSQL	batch-with-updates	batch-with-updates, insert-only	Production à faible volume
MongoDB	batch-with-updates	batch-with-updates, insert-only	Production à faible volume
OracleDB	batch-with-updates	batch-with-updates, insert-only	Production à faible volume
libSQL	batch-with-updates	batch-with-updates, insert-only	Stockage par défaut, adapté au développement

Fournisseurs ne prenant pas en charge l’observabilité

Les fournisseurs de stockage suivants ne prennent pas en charge le domaine d’observabilité. Si vous utilisez l’un d’eux et avez besoin de l’observabilité, utilisez le stockage composite pour router les données d’observabilité vers un fournisseur compatible :

• Convex
• DynamoDB
• Cloudflare D1
• Cloudflare Durable Objects
• Upstash
• LanceDB

Avantages des stratégies

• realtime : visibilité immédiate, idéale pour le débogage
• batch-with-updates : débit multiplié par 10 à 100, avec cycle de vie complet des spans
• insert-only : réduction supplémentaire de 70 % des opérations de base de données, idéale pour l’analyse

Recommandations pour la production

Les données d’observabilité croissent rapidement dans les environnements de production. Une seule interaction avec un agent peut générer des centaines de spans, et les applications à fort trafic peuvent produire des milliers de traces par jour. La plupart des bases de données généralistes ne sont pas optimisées pour cette charge composée d’écritures intensives et d’ajouts uniquement.

Recommandation : ClickHouse pour la production à fort volume

ClickHouse est une base de données en colonnes conçue pour les charges d’analyse à fort volume. Il s’agit du choix recommandé pour l’observabilité en production pour les raisons suivantes :

• Optimisé pour les écritures : gère des millions d’insertions par seconde
• Compression efficace : réduit les coûts de stockage des données de trace
• Requêtes rapides : le stockage en colonnes permet de rechercher et d’agréger rapidement les traces
• Natif pour les séries temporelles : prise en charge intégrée de la conservation et du partitionnement des données selon le temps

Utiliser le stockage composite

Si vous utilisez un fournisseur qui ne prend pas en charge l’observabilité, comme Convex ou DynamoDB, ou si vous souhaitez optimiser les performances, utilisez le stockage composite pour router les données d’observabilité vers ClickHouse tout en conservant les autres données dans votre base principale.

Comportement du traitement par lots

Déclencheurs du vidage

Pour les deux stratégies par lots (batch-with-updates et insert-only), les traces sont vidées vers le stockage dès que l’une des conditions suivantes est remplie :

1. Déclencheur de taille : le tampon atteint maxBatchSize spans
2. Déclencheur temporel : maxBatchWaitMs s’est écoulé depuis le premier événement
3. Vidage d’urgence : le tampon approche de la limite maxBufferSize
4. Arrêt : force le vidage de tous les événements en attente

Gestion des erreurs

MastraStorageExporter comprend une gestion fiable des erreurs adaptée à la production :

• Logique de nouvelle tentative : délai exponentiel (500 ms, 1 s, 2 s, 4 s)
• Échecs temporaires : nouvelle tentative automatique avec délai progressif
• Échecs persistants : abandon du lot après 4 tentatives infructueuses
• Dépassement du tampon : évite les problèmes de mémoire pendant les interruptions du stockage

Événements d’observabilité abandonnés

DefaultExporter émet des événements structurés d’abandon lorsqu’il ne peut pas conserver les données d’observabilité. Enregistrez un exportateur ou un bridge avec onDroppedEvent afin de transmettre ces abandons à un système d’alerte ou de surveillance.

Les événements sont abandonnés pour deux raisons :

• unsupported-storage : le fournisseur de stockage n’implémente pas le type de signal.
• retry-exhausted : l’exportateur a réessayé un lot jusqu’à maxRetries fois avant de l’abandonner.

L’exemple suivant montre comment transmettre les détails des abandons à un endpoint de surveillance :

src/mastra/observability.ts

import { BaseExporter } from '@mastra/observability'
import type { ObservabilityDropEvent, TracingEvent } from '@mastra/core/observability'

class DropAlertExporter extends BaseExporter {
  name = 'drop-alerts'

  async onDroppedEvent(event: ObservabilityDropEvent) {
    await fetch('https://monitoring.example.com/observability-drops', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        count: event.count,
        signal: event.signal,
        reason: event.reason,
        exporterName: event.exporterName,
      }),
    })
  }

  protected async _exportTracingEvent(_event: TracingEvent) {}
}

Exemples de configuration

// Zero config - recommended for most users
new MastraStorageExporter()

// Development override
new MastraStorageExporter({
  strategy: 'realtime', // Immediate visibility for debugging
})

// High-throughput production
new MastraStorageExporter({
  maxBatchSize: 2000, // Larger batches
  maxBatchWaitMs: 10000, // Wait longer to fill batches
  maxBufferSize: 50000, // Handle longer outages
})

// Low-latency production
new MastraStorageExporter({
  maxBatchSize: 100, // Smaller batches
  maxBatchWaitMs: 1000, // Flush quickly
})

Ressources associées

• Vue d’ensemble du traçage
• MastraPlatformExporter
• Stockage composite : combinez plusieurs fournisseurs de stockage
• Configuration du stockage