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

# Journalisation

Le système de journalisation de Mastra capture l’exécution des fonctions, les données d’entrée et les réponses de sortie dans un format structuré.

Lors d’un déploiement sur Mastra Platform, les journaux s’affichent dans le tableau de bord. Dans les environnements auto-hébergés ou personnalisés, ils peuvent être dirigés vers des fichiers ou des services externes selon les transports configurés.

**Pour les agents d’IA :** Exécutez `npx mastra api log list '{"level":"error","page":0,"perPage":50}'` pour inspecter directement les journaux d’erreur récents au lieu d’ouvrir Studio ou d’écrire un script temporaire. La commande nécessite un serveur Mastra en cours d’exécution avec la journalisation de l’observabilité configurée ; démarrez le serveur local avec `npx mastra dev`, ou transmettez l’URL de base du serveur accessible avec `--url`. Exécutez `npx mastra api log list --schema` avant de créer d’autres filtres. Installez la skill de Mastra avec `npx skills add mastra-ai/skills --skill mastra` pour disposer d’instructions complètes sur la découverte de l’API CLI, le ciblage, le schéma, l’authentification et la gestion des erreurs.

## Configurer les journaux avec `PinoLogger`

Lorsque vous [initialisez un nouveau projet Mastra](https://mastra.zisheng.pro/fr/guides/getting-started/quickstart) à l’aide de la CLI, `PinoLogger` est inclus par défaut.

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

export const mastra = new Mastra({
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
})
```

Consultez la référence de [PinoLogger](https://mastra.zisheng.pro/fr/reference/logging/pino-logger) pour découvrir toutes les options de configuration disponibles.

## Enregistrer les journaux dans le stockage d’observabilité

Lorsque l’[observabilité](https://mastra.zisheng.pro/fr/docs/observability/overview) est configurée, tous les appels du logger sont automatiquement transférés vers votre stockage d’observabilité. Ainsi, chaque appel à `debug`, `info`, `warn`, `error` et `trackException` provenant de votre application ou des composants internes de Mastra est enregistré avec vos traces.

Aucune modification du code n’est nécessaire. Mastra enveloppe le logger configuré afin qu’il écrive simultanément dans le logger d’origine, qu’il s’agisse de la console, d’un fichier ou d’un transport personnalisé, et dans le système d’observabilité.

### Configurer le niveau des journaux d’observabilité

Vous pouvez contrôler les niveaux de journaux qui atteignent le stockage d’observabilité indépendamment du logger de la console. Ajoutez une option `logging` à la configuration de votre instance d’observabilité :

```typescript
import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'Mastra', level: 'debug' }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter()],
        logging: {
          enabled: true, // set to false to disable log forwarding
          level: 'info', // minimum level: 'debug' | 'info' | 'warn' | 'error' | 'fatal'
        },
      },
    },
  }),
})
```

Dans cet exemple, le logger de la console produit tous les niveaux à partir de `debug`, mais seuls `info` et les niveaux supérieurs sont écrits dans le stockage d’observabilité. Votre stockage reste ainsi propre, tout en conservant une sortie détaillée dans la console pendant le développement.

| Option    | Type       | Valeur par défaut | Description                                                                                                       |
| --------- | ---------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `enabled` | `boolean`  | `true`            | Définissez cette option sur `false` pour désactiver tout transfert des journaux vers le stockage d’observabilité. |
| `level`   | `LogLevel` | `'debug'`         | Niveau de gravité minimal. Les journaux situés en dessous de ce niveau sont ignorés.                              |

### Interroger les journaux

Les journaux écrits dans le stockage d’observabilité peuvent être interrogés au moyen du SDK client Mastra :

```typescript
import { MastraClient } from '@mastra/client-js'

const client = new MastraClient()

const logs = await client.listLogsVNext({
  filters: { level: 'error' },
  pagination: { page: 1, perPage: 50 },
  orderBy: { field: 'timestamp', direction: 'desc' },
})
```

Avec un backend de stockage persistant tel que DuckDB ou ClickHouse, les journaux survivent aux redémarrages et restent disponibles pour l’analyse historique.

## Personnaliser les journaux

Mastra donne accès à une instance de logger au moyen de la méthode `mastra.getLogger()`, disponible dans les étapes de workflow comme dans les outils. Le logger prend en charge les niveaux de gravité standard : `debug`, `info`, `warn` et `error`.

### Journaliser depuis les étapes d’un workflow

Dans une étape de workflow, accédez au logger au moyen du paramètre `mastra` de la fonction `execute`. Vous pouvez journaliser des messages pertinents pour l’exécution de l’étape.

```typescript
import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const step1 = createStep({
  execute: async ({ mastra }) => {
    const logger = mastra.getLogger();
    logger.info("workflow info log");

    return {
      output: ""
    };
  }
});

export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();
```

### Journaliser depuis les outils

De même, les outils ont accès à l’instance du logger au moyen du paramètre `mastra`. Utilisez-la pour journaliser l’activité propre aux outils pendant l’exécution.

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const testTool = createTool({
  execute: async (inputData, context) => {
    const logger = context?.mastra.getLogger()
    logger?.info('tool info log')

    return {
      output: '',
    }
  },
})
```

### Journaliser avec des données supplémentaires

Les méthodes du logger acceptent un second argument facultatif pour les données supplémentaires. Transmettez un objet structuré afin de pouvoir filtrer les journaux dans le stockage d’observabilité.

```typescript
import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const step1 = createStep({
  execute: async ({ mastra }) => {
    const testAgent = mastra.getAgent("testAgent");
    const logger = mastra.getLogger();

    logger.info("workflow info log", { agent: testAgent });

    return {
      output: ""
    };
  }
});

export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();
```