> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://mastra.zisheng.pro/fr/reference/storage/clickhouse) au moyen du [stockage composite](https://mastra.zisheng.pro/fr/reference/storage/composite). Consultez les [recommandations pour la production](#production-recommendations) 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

```typescript
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é :

```typescript
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

```typescript
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](https://mastra.zisheng.pro/fr/reference/storage/clickhouse)** | insert-only        | insert-only                     | Production à fort volume                     |
| **[PostgreSQL](https://mastra.zisheng.pro/fr/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | Production à faible volume                   |
| **[MSSQL](https://mastra.zisheng.pro/fr/reference/storage/mssql)**           | batch-with-updates | batch-with-updates, insert-only | Production à faible volume                   |
| **[MongoDB](https://mastra.zisheng.pro/fr/reference/storage/mongodb)**       | batch-with-updates | batch-with-updates, insert-only | Production à faible volume                   |
| **[OracleDB](https://mastra.zisheng.pro/fr/reference/storage/oracledb)**     | batch-with-updates | batch-with-updates, insert-only | Production à faible volume                   |
| **[libSQL](https://mastra.zisheng.pro/fr/reference/storage/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](https://mastra.zisheng.pro/fr/reference/storage/composite) pour router les données d’observabilité vers un fournisseur compatible :

- [Convex](https://mastra.zisheng.pro/fr/reference/storage/convex)
- [DynamoDB](https://mastra.zisheng.pro/fr/reference/storage/dynamodb)
- [Cloudflare D1](https://mastra.zisheng.pro/fr/reference/storage/cloudflare-d1)
- [Cloudflare Durable Objects](https://mastra.zisheng.pro/fr/reference/storage/cloudflare)
- [Upstash](https://mastra.zisheng.pro/fr/reference/storage/upstash)
- [LanceDB](https://mastra.zisheng.pro/fr/reference/storage/lance)

### 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](https://mastra.zisheng.pro/fr/reference/storage/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](https://mastra.zisheng.pro/fr/reference/storage/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 :

```typescript
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

```typescript
// 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](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview)
- [MastraPlatformExporter](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/mastra-platform)
- [Stockage composite](https://mastra.zisheng.pro/fr/reference/storage/composite) : combinez plusieurs fournisseurs de stockage
- [Configuration du stockage](https://mastra.zisheng.pro/fr/docs/storage/overview)