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

# 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](https://mastra.zisheng.pro/fr/docs/studio/observability) 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](https://mastra.zisheng.pro/fr/guides/migrations/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) :**

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

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

```typescript
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é](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) 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**:

```bash
npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Bun**:

```bash
bun add @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',
              },
            },
          }),
        ],
      },
    },
  }),
})
```

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](https://mastra.zisheng.pro/fr/docs/observability/integrations/overview) 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) :**

```typescript
import { Mastra } from '@mastra/core'

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

**Après (observabilité v1) :**

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

```bash
npm install @mastra/observability@latest
```

**pnpm**:

```bash
pnpm add @mastra/observability@latest
```

**Yarn**:

```bash
yarn add @mastra/observability@latest
```

**Bun**:

```bash
bun add @mastra/observability@latest
```

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

```diff
+ 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.

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

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

```diff
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é](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview).

### 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](https://mastra.zisheng.pro/fr/docs/observability/integrations/overview) 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 :

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

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

```bash
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 :

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

```bash
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](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/arize)      | [Référence](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/arize)      |
| Braintrust                                                      | **Braintrust**        | [Guide](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/braintrust) | [Référence](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/braintrust) |
| Langfuse                                                        | **Langfuse**          | [Guide](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/langfuse)   | [Référence](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/langfuse)   |
| LangSmith                                                       | **LangSmith**         | [Guide](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/langsmith)  | [Référence](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/langsmith)  |
| Dash0, Laminar, New Relic, SigNoz, Traceloop, OTEL personnalisé | **OpenTelemetry**     | [Guide](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/otel)       | [Référence](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/otel)       |
| LangWatch                                                       | \<bientôt disponible> | -                                                                                           | -                                                                                               |

### Installation

**Exporters dédiés** (Arize, Braintrust, Langfuse, LangSmith) :

**npm**:

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

**pnpm**:

```bash
pnpm add @mastra/[exporter-name]-exporter
```

**Yarn**:

```bash
yarn add @mastra/[exporter-name]-exporter
```

**Bun**:

```bash
bun add @mastra/[exporter-name]-exporter
```

**Exporter OpenTelemetry** (Dash0, Laminar, New Relic, SigNoz, Traceloop) :

**npm**:

```bash
npm install @mastra/otel-exporter@latest
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest
```

Ajoutez le package de protocole requis pour votre fournisseur ; consultez le [guide OTEL](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/otel).