La journalisation des évènements avec log4j

JCMS utilise la librairie Apache log4j 1.2 pour sa gestion d'évènements. Cet article décrit le paramétrage et l'utilisation de cette API dans JCMS. Une connaissance rudimentaire des principes de log4j est requise. Référez-vous aux liens en fin de ce document pour trouver plus d'information à ce sujet.

Les Loggers

Pour rappel, chaque événement est émit par un logger, qui représente une catégorie de trace, caractérisé par :

• un nom hiérarchique, généralement similaire au nom de la classe émettrice de l'événement (com.jalios.jcms.Channel par exemple).
• un niveau (INFO, DEBUG, WARN, ERROR, FATAL)

Tous les loggers utilisés dans JCMS dérivent (au sens hiérarchique de log4j) d'un des loggers suivants :

• com.jalios : Classes internes Jalios (jcms, jtaglib, jstore, jdring, jspengine, ...)
• custom : Classes du package custom. C'est dans cette hiérarchie que se trouveront vos évènements si vous réalisez des développements dans JCMS sans passer par un module, bien que vous puissez spécifier un tout autre logger.
• generated : Classes générées (portlet, types de contenus ...).
• jsp : Pour tous les évènements émis depuis un jsp, le nom du logger sera similaire au chemin d'accès du jsp sur lequel la requête est effectuée. Par exemple un évènements émit depuis l'éditeur d'un Article sera émis par le logger jsp.types.Article.editArticle_jsp
• jcmsplugin: Pour certains évènements concernants les modules, le nom du logger contiendra le nom du module concerné. Par exemple, un évènement émit par le module Blog, sera émis par le logger jcmsplugin.BlogPlugin. Les modules utilisent également des loggers corredondant à leur nom de package java, par exemple com.jalios.jcmsplugin.blog, ils sont alors pris en charge par le logger com.jalios précédement évoqué.

Les Appenders

A chaque logger est associé un ou plusieurs appenders qui vont définir la façon dont les événements émis par un logger sont transmis à l'exploitation (via la console d'erreur, par mail, dans un fichier de log, dans une base de données...)

Par défaut, deux appenders sont activés pour tous les loggers de JCMS :

• CONSOLE: sur la sortie standard (console).
• ROLLFILE: vers le fichier de log WEB-INF/data/logs/jcms.log, avec une rotation journalière, limité à 100Mb par fichier, les précédents fichiers étant compressés au format gzip et avec un maximum de 50 fichiers maximum. Les évènements y sont enregistré dans un format plus détaillé (incluant notamment le nom/id de l'utilisateur authentifié, son adresse ip et le nom du thread Java courant)

D'autres appenders inactifs sont fournis a titre d'exemple :

• LOGFILE: vers le fichier de log WEB-INF/data/logs/jcms.log, avec une rotation des logs chaque semaine. Les évènements sont dans un format plus détaillé.
• SECURITY: émet sur la sortie d'erreur, un format très détaillé des évènements dont le niveau est supérieur ou égal à WARN et qui correspondent à un problème concernant la sécurité du site (voir section NDC ci dessous).
• SMTP: envoi par mail, un format très détaillé des évènements dont le niveau est supérieur ou égal à ERROR.

Configuration de log4j dans JCMS

Le fichier de configuration de log4j WEB-INF/data/log4j.xmlest chargé par JCMS au démarrage. Il est surveillé à intervalle régulier de 60 secondes pour permettre une relecture en cas de modification, ceci permet à l'exploitation de changer les réglages des appenders sans redémarrage de la webapp.

La variable d'environement com.jalios.jcms.log-file est déclarée avant le chargement du fichier de configuration. Cette variable permet de spécifier automatiquement le chemin utilisé pour l'appender logfile, ceci quelque soit l'emplacement de la webapp sur votre système (dans /WEB-INF/data/logs/jcms.log).

ATTENTION: si le fichier de configuration est relu automatiquement par log4j après une modification, et que vous souhaitez conserver l'appender logfile, l'architecture de log4j ne nous permet pas pour l'instant de conserver cette variable com.jalios.jcms.log-file disponible, il vous faut alors spécifier le chemin absolu en lieu et place de la variable.

Remplacez  ${com.jalios.jcms.log-file} par /monchemin/monappserver/meswebapp/monjcms/WEB-INF/data/logs/jcms.log

La variable MDC ChannelName (correspondant au nom du site JCMS) est déclarée (et mise à jour si besoin) pour que vous puissiez la réutiliser dans vos formats de sortie (cf. documentation de log4j pour plus d'infos sur le MDC).

NDC

Un premier contexte NDC est déclaré dans tous les threads issues d'une requête de jsp, il contient l'information concernant l'utilisateur connecté, sous cette forme :

[Addresse IP, id de l'utilisateur, Nom de l'utilisateur]

ou si l'utilisateur n'est pas authentifié :

[Addresse IP, unauthenticated user]

Un second contexte NDC peut être déclaré lorsqu'un problème lié à la sécurité du site est détecté (authentification invalide, accès non autorisé, upload rejeté, ...)

[SECURITY]

Référez vous à la section API ci-dessous si vous souhaitez émettre des message dans le contexte de sécurité de JCMS.

API

Pour uniformiser les messages d'erreur liés à des problèmes de sécurité (en général dans les jsp), vous pouvez utiliser deux méthodes statiques de JcmsUtil :

• public static void logForbiddenAccess(Logger lgr, Level level, HttpServletRequest request);
• public static void logSecurityIssue(Logger lgr, Level level, String msg);

Référez-vous à la javadoc de JcmsUtil pour plus d'information concernant ces méthodes.

Note: l'API log4j est thread-safe.