API des journaliseurs d'Astro

Ajouté à la version : astro@7.0.0

L’API des journaliseurs fournit un contrôle plus précis sur l’infrastructure de journalisation d’Astro. Elle vous permet de remplacer la sortie console par défaut par des implémentations de journalisation personnalisées et de vous connecter à des services d’agrégation de journaux.

Cette API inclut trois journaliseurs prêts à l’emploi et vous permet d’intégrer vos propres journaliseurs et de les composer.

Journaliseurs personnalisés

Si vous ne souhaitez pas utiliser l’un des journaliseurs intégrés, vous pouvez créer le vôtre.

Un journaliseur personnalisé se compose de deux parties :

• La configuration du journaliseur, qui permet à Astro de savoir quelle implémentation utiliser et quelle configuration transmettre
• L’implémentation du journaliseur, qui gère la logique de journalisation

Lorsque vous définissez un journaliseur personnalisé, vous êtes responsable de tous les journaux, même ceux émis par Astro.

La configuration du journaliseur

La configuration du journaliseur (logger) est un objet contenant un point d’entrée (entrypoint) obligatoire et une config facultative.

L’exemple suivant configure un journaliseur personnalisé exporté par le paquet @org/custom-logger et lui transmet une option level :

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  logger: {
    entrypoint: "@org/journaliseur-personnalise",
    config: {
      level: "warn"
    }
  }
});

L’implémentation du journaliseur

L’implémentation du journaliseur gère la logique de journalisation. Vous l’implémentez dans votre module de journaliseur en exportant une fonction par défaut qui prend la configuration du journaliseur en paramètre et renvoie un objet AstroLoggerDestination avec une fonction write() requise.

L’exemple suivant implémente un journaliseur minimal qui prend en compte le niveau de journalisation (level) défini dans sa configuration :

@org/journaliseur-personnalise/index.js

import { matchesLevel } from "astro/logger";

/**
 * Exemple minimal d'une implémentation de journaliseur personnalisé.
 *
 * @param {Object} [options] - Les options du journaliseur.
 * @param {import("astro").AstroLoggerLevel} [options.level] - Le niveau minimum des journaux. Par défaut "info".
 * @returns {import("astro").AstroLoggerDestination} La destination du journaliseur personnalisé.
 */
function orgLogger({ level } = { level: "info" }) {
  return {
    write(message) {
      // Utilisez cet utilitaire pour comprendre si le message doit être affiché
      if (matchesLevel(message.level, level)) {
        // enregistrez le message quelque part en tenant compte du niveau
      }
    },
  };
}

export default orgLogger;

Vous pouvez maintenant ajouter vos propres journaux lors du rendu d’une page en utilisant les API d’exécution.

Niveau de journalisation

Un niveau est un score interne et arbitraire attribué à chaque message. Lorsqu’un journaliseur est configuré avec un certain niveau, seuls les messages ayant un niveau égal ou supérieur sont affichés.

Il existe trois niveaux, du score le plus élevé au plus bas :

1. error
2. warn
3. info

L’exemple suivant configure le journaliseur JSON pour n’afficher que les messages ayant le niveau warn ou supérieur :

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.json({ level: "warn" })
});

Le paquet astro/logger expose un utilitaire matchesLevel() pour vérifier le niveau de journalisation. Cela peut être utile lors de la création d’un journaliseur personnalisé.

import { matchesLevel } from "astro/logger";

matchesLevel("error", "info");

Journaliseurs intégrés

Astro propose des journaliseurs intégrés que les applications peuvent utiliser.

logHandlers.json()

Un journaliseur qui affiche les messages au format JSON. Un journal ressemblerait à ceci :

{ "message": "<le message>", "label": "router", "level": "info", "time": "<timestamp UNIX>"  }

Options du journaliseur JSON

Type : { pretty: boolean; level: AstroLoggerLevel; }
Par défaut : { pretty: false, level: 'info' }

Ajouté à la version : astro@7.0.0

Le journaliseur json accepte les options suivantes :

• pretty : lorsque définie sur true, le journal JSON est affiché sur plusieurs lignes. La valeur par défaut est false.
• level : le niveau des journaux qui doivent être affichés.

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.json({ pretty: true })
});

logHandlers.console()

Un journaliseur qui affiche les messages en utilisant la console comme destination. En fonction du niveau du message, il utilise différents canaux :

• Les messages error sont affichés en utilisant console.error().
• Les messages warn sont affichés en utilisant console.warn().
• Les messages info sont affichés en utilisant console.info().

Options du journaliseur console

Type : { level: AstroLoggerLevel }
Par défaut : { level: 'info' }

Ajouté à la version : astro@7.0.0

Le journaliseur console accepte les options suivantes :

• level : le niveau des journaux qui doivent être affichés.

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.console({ level: 'warn' })
});

logHandlers.node()

Un journaliseur qui affiche les messages dans process.stdout et process.stderr. Les messages de niveau error sont affichés dans stderr, tandis que les autres sont affichés dans stdout.

Il s’agit du journaliseur par défaut d’Astro.

Options du journaliseur Node

Type : { level: AstroLoggerLevel }
Par défaut : { level: 'info' }

Ajouté à la version : astro@7.0.0

Le journaliseur node accepte les options suivantes :

• level : le niveau des journaux qui doivent être affichés.

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.node({ level: 'warn' })
});

logHandlers.compose()

Une fonction particulière qui permet de configurer plusieurs journaliseurs dans un ordre arbitraire. Le même message est diffusé à tous les journaliseurs.

L’exemple suivant compose le journaliseur console et le journaliseur JSON en utilisant le niveau de journalisation par défaut :

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.compose(
    logHandlers.console(),
    logHandlers.json()
  )
});

Référence des types

Les types suivants peuvent être importés depuis le module astro.

AstroRuntimeLogger

Type : { info: (message: string) => void; warn: (message: string) => void; error: (message: string) => void; }

Ajouté à la version : astro@7.0.8

Décrit les méthodes du journaliseur (logger) disponibles au moment de l’exécution pour ajouter des journaux supplémentaires lors du rendu de la page.

AstroLoggerDestination

Il s’agit de l’interface que les enregistreurs personnalisés doivent implémenter.

AstroLoggerDestination.write()

Type : (message: AstroLoggerMessage) => void

Une méthode obligatoire appelée pour chaque journal et acceptant un AstroLoggerMessage.

AstroLoggerDestination.flush()

Type : () => Promise<void> | void

Une fonction facultative appelée à la fin de chaque requête. Elle est utile pour les journaliseurs avancés qui doivent vider les messages de journal tout en maintenant la connexion à la destination active.

AstroLoggerDestination.close()

Type : () => Promise<void> | void

Une fonction facultative appelée avant l’arrêt d’un serveur. Cette fonction est généralement appelée par des adaptateurs tels que @astrojs/node.

AstroLoggerLevel

Type : 'debug' |'info' |'warn' | 'error' | 'silent'

Spécifie le niveau de verbosité des journaux :

• info, warn et error : définit le niveau minimal des journaux à afficher.
• silent : équivalent à l’option --silent de la CLI et active la journalisation silencieuse.
• debug : équivalent à l’option --debug de la CLI et active la journalisation détaillée, y compris la journalisation de Vite.

AstroLoggerMessage

Type : { label: string | null; level: AstroLoggerLevel; message: string; newLine: boolean; }

L’objet reçu par la fonction AstroLoggerDestination.write() :

• message : le message en cours de journalisation.
• level : le niveau du message.
• label : une étiquette arbitraire assignée au message de journal.
• newLine : indique si ce message doit ajouter un saut de ligne à la fin.

Référence des APIs

Les APIs suivantes peuvent être importées depuis le module astro/logger.

matchesLevel()

Type : matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel) => boolean

Étant donné deux niveaux de journalisation, la fonction indique si le premier niveau correspond au second.

import { matchesLevel } from "astro/logger";

matchesLevel("error", "info"); // true
matchesLevel("info", "error"); // false