Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

La journalisation avec le Logger NestJS

Cette leçon met en place la journalisation d'une API NestJS avec le Logger intégré. Elle présente les six niveaux, le contexte et les données structurées, puis configure le ConsoleLogger depuis le fic...

0 chapitres 0 QCM Accès gratuit
La journalisation avec le Logger NestJS

À propos de ce cours

Cette leçon met en place la journalisation d'une API NestJS avec le Logger intégré. Elle présente les six niveaux, le contexte et les données structurées, puis configure le ConsoleLogger depuis le fichier .env : niveau minimal, format texte ou JSON, masquage automatique des secrets avec l'option redact. Un middleware journalise chaque requête HTTP avec son statut, sa durée, l'utilisateur et un identifiant renvoyé au client. Toutes les sorties sont réelles : fuite d'un mot de passe dans le journal puis correction, erreur 500 et sa pile. La leçon précise ce qu'il faut journaliser ou non et comment les journaux sont collectés en production. Activités corrigées.

Objectifs de la leçon

  • Utiliser la classe Logger de NestJS avec un contexte et des données structurées.
  • Choisir le bon niveau pour chaque message et filtrer selon l'environnement.
  • Configurer le ConsoleLogger : texte ou JSON, masquage des secrets.
  • Journaliser chaque requête HTTP avec un identifiant de requête.
  • Savoir ce qu'il faut journaliser et ce qu'il ne faut jamais journaliser.

Versions: NestJS 12.5 (projet CommonJS créé avec nest new), TypeScript 6, Node.js 24, MariaDB 10.11, helmet 8.3, @nestjs/throttler 6.7. Tout le code de ce chapitre provient d'un vrai projet, api-securisee, et toutes les sorties ont réellement été obtenues en l'exécutant. Les mêmes notions s'appliquent à NestJS 10 et 11.

Pourquoi journaliser ?

En production, vous ne verrez jamais l'écran de l'utilisateur ni de console.log dans votre terminal. Le journal (log) est la seule trace de ce qui s'est passé. Il sert à :

  • diagnostiquer: « la stagiaire dit que l'enregistrement a échoué hier à 14 h 10 » ;
  • auditer: qui a supprimé cette demande, quand ?
  • détecter les attaques: 200 échecs de connexion en une minute, une série de 404 sur des identifiants qui se suivent (BOLA, leçon 19.3). L'OWASP classe l'absence de journalisation et d'alerte parmi les dix risques majeurs (A09:2025).

La journalisation dans NestJS

Niveaux, chaîne Logger → ConsoleLogger → sortie standard, et ce qu'il faut (ou non) journaliser.

Le Logger de NestJS

NestJS fournit une classe Logger (de @nestjs/common). C'est elle qui affiche les messages du démarrage ([InstanceLoader], [RoutesResolver]…). Dans vos classes, créez-en une avec un contexte, en général le nom de la classe :

📄 src/auth/auth.service.ts

import { Injectable, Logger, UnauthorizedException } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import * as bcrypt from 'bcrypt';
import { UtilisateursService } from '../utilisateurs/utilisateurs.service';
import { ConnexionDto } from './dto/connexion.dto';

// hachage factice : même durée de calcul que l'e-mail existe ou non
const HASH_FACTICE = '$2b$12$JjHDi6m01QnCj5aGFIBPeel5cTTYLfwp/CPMnYXdIUWo4c29yscNS';

@Injectable()
export class AuthService {
  private readonly logger = new Logger(AuthService.name);

  constructor(private readonly utilisateurs: UtilisateursService, private readonly jwt: JwtService) {}

  async connecter(dto: ConnexionDto, ip: string) {
    const u = await this.utilisateurs.parEmail(dto.email);
    const ok = await bcrypt.compare(dto.motDePasse, u?.motDePasseHash ?? HASH_FACTICE);
    if (!u || !ok) {
      this.logger.warn('Échec de connexion', { email: dto.email, ip });
      throw new UnauthorizedException('Identifiants incorrects'); // même message dans les deux cas
    }
    this.logger.log('Connexion réussie', { utilisateur: u.id, ip });
    return { jeton: await this.jwt.signAsync({ sub: u.id, email: u.email, role: u.role }) };
  }
}

Chaque méthode correspond à un niveau, du plus grave au plus bavard :

MéthodeQuand l'utiliserExemple du projet
fatal()l'application ne peut pas continuerconfiguration impossible à charger
error()une opération a échoué de façon imprévueerreur 500, base indisponible
warn()situation anormale mais géréeéchec de connexion, accès refusé, 404
log()événement normal et importantdémarrage, connexion réussie, compte créé, requête traitée
debug()détail utile au développeurnombre de résultats d'une recherche
verbose()trace très détailléecontenu d'un calcul intermédiaire

Le deuxième argument est un objet de données structurées ({ email, ip }) plutôt qu'une phrase où tout est collé : on peut ensuite filtrer et compter par champ (« tous les échecs pour cette IP »). Le service des demandes ajoute un message de niveau debug:

📄 src/demandes/demandes.service.ts (extrait)

    const [donnees, total] = await qb.getManyAndCount();
    this.logger.debug(`Recherche « ${recherche ?? ''} » : ${total} résultat(s)`, { utilisateur: moi.id, page });
Configurer le logger depuis .env

Par défaut, tout est affiché, en texte coloré. Le projet crée son propre ConsoleLogger (la classe utilisée par défaut par NestJS) avec trois réglages lus dans le .env:

📄 src/commun/creer-logger.ts

import { ConsoleLogger, type LogLevel } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

const TOUS: LogLevel[] = ['fatal', 'error', 'warn', 'log', 'debug', 'verbose'];

export function creerLogger(config: ConfigService) {
  const production = config.get('NODE_ENV') === 'production';
  // LOG_NIVEAUX=warn → fatal, error, warn ; par défaut : log en production, debug en développement
  const seuil = (config.get<string>('LOG_NIVEAUX') || (production ? 'log' : 'debug')) as LogLevel;
  return new ConsoleLogger({
    json: config.get('LOG_FORMAT') === 'json',
    logLevels: TOUS.slice(0, TOUS.indexOf(seuil) + 1),
    prefix: 'API',
    // jamais de secret dans les journaux, même par erreur
    redact: ['motDePasse', 'motDePasseHash', 'authorization', 'jeton'],
  });
}

📄 src/main.ts

import { NestFactory } from '@nestjs/core';
import { Logger } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import type { NestExpressApplication } from '@nestjs/platform-express';
import { AppModule } from './app.module';
import { configurerApp } from './configurer-app';
import { creerLogger } from './commun/creer-logger';

async function bootstrap() {
  // bufferLogs : les messages du démarrage attendent que notre logger soit en place
  const app = await NestFactory.create<NestExpressApplication>(AppModule, { bufferLogs: true });
  const config = app.get(ConfigService);
  app.useLogger(creerLogger(config));
  configurerApp(app, config);
  const port = config.get<number>('PORT', 3000);
  await app.listen(port);
  new Logger('Demarrage').log(`API prête sur http://localhost:${port}/api (${config.get('NODE_ENV')})`);
}
void bootstrap();
  • bufferLogs: true: les messages du démarrage sont mis en attente jusqu'à app.useLogger(), pour qu'ils utilisent déjà notre configuration ;
  • logLevels: les niveaux affichés. LOG_NIVEAUX=log garde fatal, error, warn et log;
  • json: une ligne JSON par message (plus bas) ;
  • redact: les propriétés à masquer, à toute profondeur (plus bas).

Avec la configuration de développement (niveau debug), pendant que Sami se connecte, cherche « attestation », demande une demande inexistante puis qu'une connexion échoue :

Journal du serveur (réel) :

[API] 4814  - 11/15/2026, 6:00:07 PM     LOG [Demarrage] API prête sur http://localhost:3000/api (development)
[API] 4814  - 11/15/2026, 6:00:13 PM     LOG [AuthService] Connexion réussie { utilisateur: 2, ip: '127.0.0.1' }
[API] 4814  - 11/15/2026, 6:00:13 PM     LOG [HTTP] POST /api/auth/connexion 200 267ms { requete: 'eedbfd86', ip: '127.0.0.1', utilisateur: null }
[API] 4814  - 11/15/2026, 6:00:13 PM     LOG [AuthService] Connexion réussie { utilisateur: 3, ip: '127.0.0.1' }
[API] 4814  - 11/15/2026, 6:00:13 PM     LOG [HTTP] POST /api/auth/connexion 200 244ms { requete: '0bb0a4c3', ip: '127.0.0.1', utilisateur: null }
[API] 4814  - 11/15/2026, 6:00:14 PM     LOG [AuthService] Connexion réussie { utilisateur: 1, ip: '127.0.0.1' }
[API] 4814  - 11/15/2026, 6:00:14 PM     LOG [HTTP] POST /api/auth/connexion 200 257ms { requete: '28ed489e', ip: '127.0.0.1', utilisateur: null }
[API] 4814  - 11/15/2026, 6:00:14 PM   DEBUG [DemandesService] Recherche « attestation » : 1 résultat(s) { utilisateur: 2, page: 1 }
[API] 4814  - 11/15/2026, 6:00:14 PM     LOG [HTTP] GET /api/demandes?recherche=attestation 200 7ms { requete: '5b94e688', ip: '127.0.0.1', utilisateur: 2 }
[API] 4814  - 11/15/2026, 6:00:14 PM    WARN [HTTP] GET /api/demandes/99 404 5ms { requete: '4654ee69', ip: '127.0.0.1', utilisateur: 2 }
[API] 4814  - 11/15/2026, 6:00:14 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', ip: '127.0.0.1' }
[API] 4814  - 11/15/2026, 6:00:14 PM    WARN [HTTP] POST /api/auth/connexion 401 252ms { requete: 'c8022e1e', ip: '127.0.0.1', utilisateur: null }

Chaque ligne indique le préfixe (API), le numéro de processus, la date, le niveau, le contexte entre crochets, le message et les données. Avec LOG_NIVEAUX=warn, seuls les problèmes restent :

Journal du serveur (réel) :

[API] 4869  - 11/15/2026, 6:00:27 PM    WARN [HTTP] GET /api/demandes/99 404 8ms { requete: '73ec8641', ip: '127.0.0.1', utilisateur: 2 }
[API] 4869  - 11/15/2026, 6:00:27 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', ip: '127.0.0.1' }
[API] 4869  - 11/15/2026, 6:00:27 PM    WARN [HTTP] POST /api/auth/connexion 401 253ms { requete: '707992e9', ip: '127.0.0.1', utilisateur: null }

Nouveau dans NestJS 12 : NEST_LOG_LEVEL. Sans configuration, le logger par défaut lit cette variable d'environnement (warn, >=debug ou une liste comme warn,error). Dans un projet qui n'a pas de creerLogger, NEST_LOG_LEVEL=warn npm run start donne réellement :

[Nest] 5055  - 11/15/2026, 6:01:14 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', ip: '127.0.0.1' }
[Nest] 5055  - 11/15/2026, 6:01:14 PM    WARN [HTTP] POST /api/auth/connexion 401 269ms { requete: '275871cb', ip: '127.0.0.1', utilisateur: null }

Dès qu'on passe logLevels au logger, comme dans notre projet, c'est cette valeur qui compte.

Journaliser chaque requête HTTP

Un middleware voit passer toutes les requêtes. En écoutant l'événement finish de la réponse, il connaît le statut final et la durée :

📄 src/commun/journal-http.middleware.ts

import { Injectable, Logger, NestMiddleware } from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import type { NextFunction, Request, Response } from 'express';

@Injectable()
export class JournalHttpMiddleware implements NestMiddleware {
  private readonly logger = new Logger('HTTP');

  use(req: Request, res: Response, next: NextFunction) {
    const debut = performance.now();
    const id = randomUUID().slice(0, 8);
    res.setHeader('X-Request-Id', id);
    res.on('finish', () => {
      const duree = Math.round(performance.now() - debut);
      const user = (req as Request & { user?: { id: number } }).user;
      const ligne = `${req.method} ${req.originalUrl} ${res.statusCode} ${duree}ms`;
      const contexte = { requete: id, ip: req.ip, utilisateur: user?.id ?? null };
      if (res.statusCode >= 500) this.logger.error(ligne, contexte);
      else if (res.statusCode >= 400) this.logger.warn(ligne, contexte);
      else this.logger.log(ligne, contexte);
    });
    next();
  }
}

📄 src/app.module.ts (extrait)

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(JournalHttpMiddleware).forRoutes('*path');
  }
  • Le niveau dépend du statut : log pour 2xx-3xx, warn pour 4xx, error pour 5xx.
  • Pourquoi un middleware et pas un intercepteur ? Les intercepteurs s'exécutent après les guards : une requête refusée par le ThrottlerGuard (429) ou l'AuthGuard (401, 403) n'atteint jamais l'intercepteur, et ce sont justement les requêtes suspectes. Le middleware s'exécute avant tout le reste.
  • req.user est rempli plus tard par l'AuthGuard; comme on le lit à la fin de la réponse, l'utilisateur est connu.
  • X-Request-Id est renvoyé au client. Si un utilisateur signale une erreur, Angular peut afficher ce code (« erreur 3f21… ») : vous retrouvez immédiatement la ligne correspondante dans le journal.
Le format JSON pour la production

Le texte est agréable à lire, mais difficile à analyser par un programme. En production, les journaux sont envoyés à un outil de collecte (Grafana Loki, Elasticsearch, Datadog…) qui attend une ligne JSON par message. Avec LOG_FORMAT=json, le même scénario donne :

Journal du serveur (réel) :

{"level":"log","pid":4921,"timestamp":1794762038706,"message":"Connexion réussie","context":"AuthService","params":{"utilisateur":2,"ip":"127.0.0.1"}}
{"level":"log","pid":4921,"timestamp":1794762038716,"message":"POST /api/auth/connexion 200 269ms","context":"HTTP","params":{"requete":"7bfaebc7","ip":"127.0.0.1","utilisateur":null}}
{"level":"log","pid":4921,"timestamp":1794762038980,"message":"Connexion réussie","context":"AuthService","params":{"utilisateur":3,"ip":"127.0.0.1"}}
{"level":"log","pid":4921,"timestamp":1794762038982,"message":"POST /api/auth/connexion 200 257ms","context":"HTTP","params":{"requete":"a6774070","ip":"127.0.0.1","utilisateur":null}}
{"level":"log","pid":4921,"timestamp":1794762039240,"message":"Connexion réussie","context":"AuthService","params":{"utilisateur":1,"ip":"127.0.0.1"}}
{"level":"log","pid":4921,"timestamp":1794762039241,"message":"POST /api/auth/connexion 200 252ms","context":"HTTP","params":{"requete":"0500c389","ip":"127.0.0.1","utilisateur":null}}
{"level":"debug","pid":4921,"timestamp":1794762039260,"message":"Recherche « attestation » : 1 résultat(s)","context":"DemandesService","params":{"utilisateur":2,"page":1}}
{"level":"log","pid":4921,"timestamp":1794762039261,"message":"GET /api/demandes?recherche=attestation 200 7ms","context":"HTTP","params":{"requete":"94fa2dd1","ip":"127.0.0.1","utilisateur":2}}
{"level":"warn","pid":4921,"timestamp":1794762039273,"message":"GET /api/demandes/99 404 6ms","context":"HTTP","params":{"requete":"4374c365","ip":"127.0.0.1","utilisateur":2}}
{"level":"warn","pid":4921,"timestamp":1794762039528,"message":"Échec de connexion","context":"AuthService","params":{"email":"sami@exemple.tn","ip":"127.0.0.1"}}
{"level":"warn","pid":4921,"timestamp":1794762039529,"message":"POST /api/auth/connexion 401 249ms","context":"HTTP","params":{"requete":"586aa2ee","ip":"127.0.0.1","utilisateur":null}}

Chaque champ devient interrogeable : level = "warn" AND context = "AuthService" donne tous les échecs de connexion ; params.requete = "c7029a9f" retrouve une requête précise. timestamp est en millisecondes depuis 1970.

Ne jamais journaliser de secret

Un journal est lu par beaucoup de monde (développeurs, hébergeur, outil de collecte) et gardé longtemps. Il ne doit contenir ni mot de passe, ni jeton, ni en-tête Authorization, ni secret. L'erreur arrive vite : un développeur remplace { email: dto.email, ip } par { ...dto, ip } pour « avoir plus de détails ». Sans protection :

Journal du serveur (réel) :

[API] 4972  - 11/15/2026, 6:00:50 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', motDePasse: 'azerty', ip: '127.0.0.1' }

Le mot de passe essayé est en clair dans le journal (souvent, c'est le vrai mot de passe avec une faute de frappe, ou celui d'un autre site). Avec l'option redact du ConsoleLogger (NestJS 12), le même code donne :

Journal du serveur (réel) :

[API] 5015  - 11/15/2026, 6:01:02 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', motDePasse: '[REDACTED]', ip: '127.0.0.1' }

redact est un filet de sécurité: il masque les propriétés citées dans les objets de données, mais pas le texte du message lui-même (this.logger.log(`mot de passe : ${mdp}`) serait affiché en clair). La règle reste de ne passer au logger que ce qui est utile.

Les erreurs imprévues

Vous n'avez rien à faire pour les erreurs 500 : le filtre d'exceptions de NestJS les journalise avec la pile d'appels (contexte ExceptionsHandler), et le middleware ajoute la ligne HTTP :

Journal du serveur (réel) :

[API] 4773  - 11/15/2026, 6:00:01 PM   ERROR [ExceptionsHandler] Error: connect ECONNREFUSED 10.0.0.12:3306 (utilisateur 'api')
    at SanteController.panne (/projet/dist/sante/sante.controller.js:18:15)
[API] 4773  - 11/15/2026, 6:00:01 PM   ERROR [HTTP] GET /api/sante/panne 500 10ms { requete: '420a21c9', ip: '127.0.0.1', utilisateur: null }
Les journaux en production
  • L'application écrit sur la sortie standard (stdout) et ne gère pas de fichiers elle-même : PM2, systemd ou Docker (chapitre 20) récupèrent cette sortie, l'horodatent, la stockent et font la rotation (découpage et suppression des anciens fichiers).
  • Niveau log (ou warn si le trafic est important), format json si un outil de collecte est utilisé.
  • Durée de conservation limitée : les journaux contiennent des données personnelles (adresses IP, e-mails), soumises à la réglementation sur la protection des données.
  • Des alertes: un journal que personne ne lit ne détecte rien. Exemple : prévenir l'administrateur au-delà de 50 réponses 401 ou 429 en 5 minutes.
  • Pour des besoins plus avancés (très gros volumes, envoi direct vers un service), des bibliothèques comme nestjs-pino remplacent le logger par défaut ; les principes de cette leçon restent les mêmes.
Activités

Activité 1 Choisir le niveau

Quel niveau pour : (a) « Serveur SMTP injoignable, e-mail de bienvenue non envoyé » ; (b) « Demande 42 validée par admin 1 » ; (c) « Requête SQL générée : SELECT … » ; (d) « JWT_SECRET absent, arrêt » ; (e) « Tentative d'accès à la demande 3 par l'utilisateur 2 : refusé » ?

Voir le corrigé

(a) error (ou warn si un nouvel essai est prévu) ; (b) log: événement métier important, utile à l'audit ; (c) debug ou verbose, jamais en production (elle peut contenir des données personnelles) ; (d) fatal; (e) warn: c'est peut-être une attaque BOLA.

Activité 2 Mettre en place la journalisation

Dans votre projet, sur une branche observabilite/journal: ajoutez creerLogger, le middleware HTTP et les variables LOG_FORMAT et LOG_NIVEAUX dans .env.example. Ajoutez des messages log pour les créations et suppressions, et warn pour les échecs de connexion. Lancez l'API en texte puis en JSON et joignez un extrait des deux à la Pull Request.

Voir le corrigé

Vérifiez que .env reste dans le .gitignore et que seul .env.example est versionné. Pensez à retirer les console.log restants : grep -rn "console.log" src. Commit : feat(observabilite): journalisation structurée.

Activité 3 Trouver la fuite

Quelles lignes posent problème, et comment les corriger ? (a) this.logger.log('Connexion', req.headers); (b) this.logger.debug(`Nouveau jeton : ${jeton}`); (c) this.logger.warn('Échec', { email, ip }); (d) this.logger.error('Paiement refusé', { carte: dto.numeroCarte }).

Voir le corrigé

(a) les en-têtes contiennent Authorization (et les cookies) : ne journaliser que les champs utiles ; redact masquerait authorization, mais pas un cookie. (b) jeton en clair dans le texte du message : redact ne s'applique pas aux chaînes ; supprimer la ligne. (c) correct. (d) numéro de carte : interdit, journaliser seulement un identifiant de transaction ou les 4 derniers chiffres.

Activité 4 Afficher l'identifiant de requête dans Angular

Modifiez l'intercepteur Angular du chapitre 18 : en cas d'erreur 500, affichez « Une erreur est survenue (référence : XXXX) » avec la valeur de l'en-tête X-Request-Id. Quelle configuration CORS est nécessaire pour qu'Angular puisse lire cet en-tête ?

Voir le corrigé

Dans l'intercepteur : catchError((e: HttpErrorResponse) => { if (e.status === 500) afficher(`Une erreur est survenue (référence : ${e.headers.get('X-Request-Id')})`); return throwError(() => e); }). Par défaut, le navigateur ne laisse lire au JavaScript d'une autre origine que quelques en-têtes simples : côté API, app.enableCors({ origin: …, exposedHeaders: ['X-Request-Id'] }).

À retenir

  • new Logger(Contexte.name), un niveau par usage : fatal, error, warn, log, debug, verbose.
  • Le message en texte, les détails dans un objet de données structurées.
  • bufferLogs + app.useLogger(); niveaux et format (texte ou JSON) lus dans .env.
  • Un middleware journalise toutes les requêtes, y compris celles refusées par les guards ; X-Request-Id relie client et journal.
  • Jamais de mot de passe, de jeton ou de secret dans les journaux ; redact en filet de sécurité.
  • En production : stdout collecté par PM2/Docker, rotation, conservation limitée, alertes.

Cet article vous a-t-il aidé ?