Aller au contenu

Écrire des logs filtrables par niveau

Configurez votre service pour écrire ses logs en JSON, un objet par ligne avec un niveau, afin de les filtrer à l'écran et au téléchargement.

GuideDéveloppeur
Durée
10 min
Voir en Markdown

Wakastart lit le niveau de chaque ligne de log de votre service (DEBUG, INFO, WARN, ERROR…). C'est ce niveau qui permet de ne garder, dans l'onglet Logs comme dans un fichier téléchargé, que les avertissements et les erreurs. Pour qu'il soit reconnu, votre service écrit ses logs en JSON, un objet par ligne, avec un champ level : en pratique, une ligne de configuration de votre bibliothèque de logs.

Avant de commencer

  • Votre service est déployé et vous avez accès à son onglet Logs (voir Consulter les logs d'un service).
  • Repérez la bibliothèque de logs utilisée par votre code (pino, winston, logger de NestJS, log/slog, structlog…).

Comment le niveau est lu

  • Le seul canal de logs d'un service est la sortie standard (stdout) ou la sortie d'erreur (stderr) de son conteneur. Il n'y a ni agent, ni endpoint, ni SDK à brancher. Un fichier écrit dans le conteneur n'est pas collecté.
  • stderr ne fixe pas le niveau : une ligne {"level":"info"} écrite sur stderr reste INFO. Seul le contenu de la ligne compte.
  • Une ligne est lue comme JSON si elle commence par { et forme un objet valide. Les codes couleur du terminal sont retirés avant la lecture.
  • Le niveau est pris dans la première clé présente parmi level, severity, log.level, log → level, levelname et @l. Les valeurs reconnues (info, warning, 30, INFO+2…) sont listées dans la référence.
  • Seule exception au JSON : le texte par défaut de NestJS ([Nest] 1234 - … WARN [Contexte] message) est reconnu. Tout autre texte libre (console.log, print, fmt.Println) est conservé, affiché et téléchargé, mais sans niveau, même s'il contient le mot ERROR.

Configurer votre service

Activer la sortie JSON de votre bibliothèque

Appliquez le réglage de votre pile :

PileRéglage
NestJS 11 ou plusNestFactory.create(AppModule, { logger: new ConsoleLogger({ json: true }) }) ; les couleurs sont désactivées d'office en JSON
NestJS avant la version 11Rien d'obligatoire, le texte par défaut est reconnu. Pour du JSON : nestjs-pino
Node.js, pinoRien : pino écrit du JSON sur stdout par défaut, avec un level numérique
Node.js, winstonformat.json() (le format par défaut de createLogger), sans format.colorize()
Go, log/slogslog.New(slog.NewJSONHandler(os.Stdout, nil))
Go, zapzap.NewProduction()
Go, logruslog.SetFormatter(&log.JSONFormatter{})
Python, python-json-loggerJsonFormatter("{levelname}{message}", style="{") : un JsonFormatter() sans argument n'écrit pas le niveau
Python, structlogstructlog.configure(processors=[structlog.processors.add_log_level, structlog.processors.JSONRenderer()]) : gardez add_log_level
Java, Logback<encoder class="net.logstash.logback.encoder.LogstashEncoder" /> dans un ConsoleAppender (dépendance net.logstash.logback:logstash-logback-encoder)
Java, Log4j 2<JsonTemplateLayout/> dans un appender Console (dépendance org.apache.logging.log4j:log4j-layout-template-json)
.NET, Serilog.WriteTo.Console(new RenderedCompactJsonFormatter()) (paquet Serilog.Formatting.Compact)
Autres pilesLes bibliothèques ECS logging d'Elastic, qui écrivent la clé log.level

Par exemple, pour NestJS 11 :

TypeScript
import { ConsoleLogger } from "@nestjs/common";
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    logger: new ConsoleLogger({ json: true }),
  });
  await app.listen(3000);
}
bootstrap();

Les appels existants (this.logger.warn(...), this.logger.error(...)) ne changent pas.

Garder chaque événement sur une ligne

Passez les erreurs à votre logger plutôt que de les imprimer : en JSON, la pile d'appels est rangée dans le même objet (champ stack avec NestJS) et garde son niveau. Écrite en texte, une pile d'appels produit une entrée par ligne, toutes sans niveau.

Vérifier vos niveaux personnalisés

Si votre code définit ses propres niveaux, vérifiez qu'ils figurent dans les valeurs reconnues. Une valeur inconnue (par exemple audit) donne une ligne sans niveau, jamais un faux niveau.

Déployer

Lancez un build puis déployez le service (voir Builds et déploiements).

Avant et après, pour le même événement :

Texte
[Nest] 19096  - 10/08/2026, 12:27:02 PM   ERROR [OrdersService] Payment failed
Error: card_declined
    at OrdersService.pay (/app/dist/orders/orders.service.js:42:13)
JSON
{"level":"error","pid":19096,"timestamp":1760012822000,"message":"Payment failed","context":"OrdersService","stack":"Error: card_declined\n    at OrdersService.pay (/app/dist/orders/orders.service.js:42:13)"}

Dans le premier cas, seule la première ligne a un niveau : avec Erreurs et plus et Inclure les lignes sans niveau décochée, la pile d'appels disparaît. Dans le second, l'événement entier est filtré avec son niveau.

Vérifier le résultat

  1. Dans l'onglet Logs du service, choisissez Warn et plus dans Niveau minimum, puis décochez Inclure les lignes sans niveau.
  2. Déclenchez un avertissement ou une erreur dans votre application.

Résultat attendu : la ligne apparaît avec son niveau. Si plus rien ne s'affiche alors que votre service écrit des avertissements, ses lignes n'ont pas de niveau reconnu : voir Mes logs n'ont pas de niveau.

Attention

Une ligne de plus de 1 Mo est découpée en morceaux d'environ 1 Mo, sans perte, mais aucun morceau n'est un JSON complet : ils restent sans niveau. Ne journalisez pas de contenus volumineux, ni de données personnelles ou de secrets.

Voir aussi