À propos de ce cours
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).
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éthode | Quand l'utiliser | Exemple du projet |
|---|---|---|
fatal() | l'application ne peut pas continuer | configuration impossible à charger |
error() | une opération a échoué de façon imprévue | erreur 500, base indisponible |
warn() | situation anormale mais gérée | échec de connexion, accès refusé, 404 |
log() | événement normal et important | démarrage, connexion réussie, compte créé, requête traitée |
debug() | détail utile au développeur | nombre de résultats d'une recherche |
verbose() | trace très détaillée | contenu 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=loggardefatal,error,warnetlog;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 :
logpour 2xx-3xx,warnpour 4xx,errorpour 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.userest rempli plus tard par l'AuthGuard; comme on le lit à la fin de la réponse, l'utilisateur est connu.X-Request-Idest 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(ouwarnsi le trafic est important), formatjsonsi 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-pinoremplacent 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-Idrelie client et journal. - Jamais de mot de passe, de jeton ou de secret dans les journaux ;
redacten filet de sécurité. - En production : stdout collecté par PM2/Docker, rotation, conservation limitée, alertes.
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !