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 à l’aide de la CLI, PinoLogger est inclus par défaut.

src/mastra/index.ts

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 pour découvrir toutes les options de configuration disponibles.

Enregistrer les journaux dans le stockage d’observabilité

Lorsque l’observabilité 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é :

src/mastra/index.ts

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 :

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.

src/mastra/workflows/test-workflow.ts

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.

src/mastra/tools/test-tool.ts

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

src/mastra/workflows/test-workflow.ts

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();