Niveaux de log et gestion dynamique via Actuator

Comprendre les niveaux de log

Les niveaux de log sont un mécanisme fondamental pour contrôler la quantité et le type d'informations enregistrées par une application. Ils permettent de filtrer les messages de log en fonction de leur sévérité ou de leur importance. Les frameworks de logging comme Logback, Log4j2 et JUL utilisent une hiérarchie de niveaux standard :

• TRACE : Le niveau le plus détaillé, utilisé pour suivre l'exécution pas à pas, souvent très verbeux.
• DEBUG : Informations utiles pour le débogage, moins détaillées que TRACE mais plus que INFO.
• INFO : Messages informatifs sur la progression normale de l'application (démarrage, configuration, étapes majeures). C'est souvent le niveau par défaut en production.
• WARN (ou WARNING) : Indique une situation potentiellement problématique ou inattendue, mais qui n'empêche pas l'application de continuer à fonctionner.
• ERROR : Signale une erreur sérieuse qui a empêché une opération de se terminer correctement, mais l'application peut potentiellement continuer (avec des fonctionnalités dégradées).
• FATAL : (Principalement dans Log4j2) Indique une erreur très grave qui va probablement entraîner l'arrêt de l'application.
• OFF : Désactive complètement le logging pour un logger donné.

Ces niveaux sont ordonnés (TRACE < DEBUG < INFO < WARN < ERROR). Lorsqu'un niveau est défini pour un logger, celui-ci enregistrera les messages de ce niveau et de tous les niveaux supérieurs. Par exemple, si un logger est configuré au niveau INFO, il enregistrera les messages INFO, WARN et ERROR, mais ignorera les messages DEBUG et TRACE.

Les loggers sont également hiérarchiques, généralement basés sur les noms de packages ou de classes. Si le niveau d'un logger spécifique n'est pas défini explicitement, il hérite du niveau de son parent le plus proche dans la hiérarchie, jusqu'au logger racine ('root logger').

Configuration des niveaux dans Spring Boot

Spring Boot permet de configurer facilement les niveaux de log via les fichiers `application.properties` ou `application.yml`, quelle que soit l'implémentation sous-jacente (Logback par défaut).

Par défaut, Spring Boot configure le logger racine au niveau INFO. Les messages INFO, WARN, et ERROR sont donc affichés sur la console.

Pour modifier les niveaux, utilisez le préfixe `logging.level.`. Vous pouvez cibler le logger racine ou des loggers spécifiques (par nom de package ou de classe) :

Dans `application.properties` :

# Niveau pour le logger racine
logging.level.root=WARN

# Niveau spécifique pour un package
logging.level.com.example.myapp.service=DEBUG

# Niveau spécifique pour une classe
logging.level.org.springframework.web=INFO
logging.level.org.hibernate.SQL=TRACE

Dans `application.yml` :

logging:
  level:
    root: WARN
    com.example.myapp.service: DEBUG
    org.springframework.web: INFO
    org.hibernate.SQL: TRACE

Ces configurations sont appliquées au démarrage de l'application. Cependant, que faire si vous avez besoin de modifier temporairement le niveau de log d'un composant spécifique en production pour diagnostiquer un problème, sans avoir à redéployer l'application ? C'est là qu'intervient Spring Boot Actuator.

Gestion dynamique avec l'endpoint `/loggers` d'Actuator

Spring Boot Actuator expose un endpoint dédié, `/actuator/loggers`, qui permet de visualiser et de modifier les niveaux de log des différents loggers de l'application à chaud, pendant qu'elle est en cours d'exécution.

Pour utiliser cette fonctionnalité, assurez-vous que :

1. La dépendance `spring-boot-starter-actuator` est ajoutée à votre projet.
2. L'endpoint `/loggers` est exposé via le web. Modifiez votre `application.properties`/`yml` si nécessaire :

# Exposer l'endpoint loggers (et health par exemple)
management.endpoints.web.exposure.include=health,loggers

Attention : Exposer l'endpoint `/loggers` sans sécurité appropriée en production est un risque. Nous aborderons la sécurisation plus loin.

Visualiser et modifier les niveaux via l'API REST

Une fois l'endpoint exposé, vous pouvez interagir avec lui via des requêtes HTTP :

• Voir tous les loggers et leurs niveaux (GET /actuator/loggers) : Retourne une structure JSON listant tous les loggers connus (y compris ceux héritant leur niveau) et leurs niveaux configurés et effectifs.

# Requête
curl http://localhost:8080/actuator/loggers

# Réponse (extrait)
{
  "levels": [
    "OFF", "FATAL", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"
  ],
  "loggers": {
    "ROOT": {
      "configuredLevel": "INFO",
      "effectiveLevel": "INFO"
    },
    "com.example.myapp": {
      "configuredLevel": null, // Hérite de ROOT
      "effectiveLevel": "INFO"
    },
    "com.example.myapp.service": {
      "configuredLevel": "DEBUG",
      "effectiveLevel": "DEBUG"
    },
    "org.springframework.web": {
      "configuredLevel": "INFO",
      "effectiveLevel": "INFO"
    },
    // ... autres loggers
  }
}

• Voir le niveau d'un logger spécifique (GET /actuator/loggers/{loggerName}) :

# Requête
curl http://localhost:8080/actuator/loggers/com.example.myapp.service

# Réponse
{
  "configuredLevel": "DEBUG",
  "effectiveLevel": "DEBUG"
}

• Modifier le niveau d'un logger (POST /actuator/loggers/{loggerName}) : Envoyez une requête POST avec un corps JSON spécifiant le nouveau `configuredLevel`. Vous pouvez passer `null` pour réinitialiser le niveau et le faire hériter de son parent.

# Requête pour passer com.example.myapp.service en TRACE
curl -X POST -H "Content-Type: application/json" \
     -d '{"configuredLevel": "TRACE"}' \
     http://localhost:8080/actuator/loggers/com.example.myapp.service

# Requête pour réinitialiser le niveau de com.example.myapp.service (héritera de ROOT)
curl -X POST -H "Content-Type: application/json" \
     -d '{"configuredLevel": null}' \
     http://localhost:8080/actuator/loggers/com.example.myapp.service

Ces modifications sont appliquées immédiatement, sans nécessiter de redémarrage. C'est extrêmement utile pour augmenter temporairement la verbosité d'un module spécifique afin d'investiguer un comportement étrange en production, puis de revenir au niveau normal une fois le problème compris.

Considérations de sécurité et cas d'usage

La capacité de modifier les niveaux de log à la volée est puissante, mais potentiellement dangereuse si elle n'est pas sécurisée. Activer le niveau TRACE sur de nombreux loggers dans une application en production peut générer une quantité massive de logs, impactant potentiellement les performances (CPU, I/O disque, réseau) et remplissant rapidement l'espace disque ou saturant les systèmes de centralisation de logs.

Il est donc impératif de sécuriser l'endpoint `/loggers` en production. Utilisez Spring Security pour restreindre l'accès à cet endpoint (et aux autres endpoints Actuator sensibles) aux seuls utilisateurs ou rôles autorisés (par exemple, les administrateurs système ou les équipes SRE).

Les cas d'usage typiques de la gestion dynamique des logs incluent :

• Diagnostic en production : Augmenter temporairement le niveau de log d'un composant suspect pour obtenir plus de détails sans redémarrer.
• Activation de logs spécifiques : Activer des logs très spécifiques (comme `org.hibernate.SQL`) pour analyser un problème de performance de base de données pendant une courte période.
• Réduction du bruit : Diminuer temporairement le niveau de log d'un composant trop verbeux si ses logs masquent des informations plus importantes.

En maîtrisant les niveaux de log et l'utilisation de l'endpoint `/loggers` d'Actuator, vous disposez d'un outil précieux pour observer et dépanner vos applications Spring Boot de manière flexible et efficace.