JCMS 5.0 utilise la librairie log4j d'Apache Jakarta 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 probablement vos évènements si vous êtes amenés à faire des développements dans JCMS, 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

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).
• 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é.

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

• 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, soit /WEB-INF/data/log4j.xml (uniquement à partir de la version 5.0.1) soit /WEB-INF/data/log4j.properties, est chargé par JCMS au démarrage (la version XML est celle chargée si les deux fichiers sont présent). 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 :
log4j.appender.logfile.File=${com.jalios.jcms.log-file}
Par :
log4j.appender.logfile.File=/monchemin/monappserver/meswebapp/monjcms/WEB-INF/data/logs/jcms.log

La variable MDC ChannelName (correspondant au nom du canal 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.