Introduction à Log4J

Le principe central de la configuration est sa hiérarchisation, c'est-à-dire que chaque Logger va hériter du niveau de son plus proche parent pour lequel on en a défini un, à moins qu'on ne lui attribue explicitement un niveau. Un Logger est parent d'un autre si son nom complet est le préfixe du second. Par exemple, le Loggercom.developpez.beuss.java sera le parent du Loggercom.developpez.beuss.java.log4j, il lui transmettra donc son niveau. Il existe un Logger particulier appelé rootLogger (Logger racine) qui est l'ancêtre de tous les Loggers existants.

L'intérêt de ce mécanisme est évident lorsque l'on utilise différentes bibliothèques au sein d'un projet qui se servent de Log4j pour journaliser les messages. Il est possible de compartimenter la configuration pour, par exemple, avoir tous les messages de débogage des classes que l'on développe, mais uniquement les messages d'erreur des bibliothèques utilisées.

Prenons par exemple un projet qui utiliserait certaines des bibliothèques commons de Jakarta. Il est fréquent que ces bibliothèques utilisent les commons logging pour journaliser les événements. Les commons logging utilisent Log4j comme système de journalisation si celui-ci est disponible. on pourra donc avoir une hiérarchie ressemblant à cela (la syntaxe utilisée n'est pas celle des fichiers de configuration log4j, celle-ci sera présentée plus loin) :

Avec une configuration de ce type, seuls les messages d'erreur des API commons seront journalisés alors que l'on aura les messages d'information provenant de Tomcat (org.apache.catalina) et les messages de débogage de l'application en cours de développement.

C'est là qu'apparait l'utilité de l'utilisation des noms complets des classes comme identifiant pour les Loggers. En procédant de cette façon, le contrôle du niveau de journalisation peut s'effectuer au niveau des packages ou même des classes.

Si vous n'affectez pas de niveau de journalisation au Logger racine, il prend automatiquement la valeur DEBUG, cela peut conduire à l'affichage de nombreux messages, aussi, il est préférable de définir un niveau manuellement.

De prime abord, le fonctionnement de la configuration des Appenders peut sembler similaire à celui des niveaux, mais ce n'est pas le cas. En effet, il ne s'agit plus d'héritage proprement dit, mais d'additivité. C'est-à-dire qu'un Logger d'un niveau donné va bénéficier de tous les Appenders de ses ancêtres en plus de ceux qui lui sont éventuellement affectés. Il est possible de « couper » la chaîne à un niveau quelconque en indiquant que l'on ne veut pas que l'additivité s'applique. Un exemple vaut mieux qu'un long discours :

Avec ce type de configuration, on peut décider par exemple que le Logger racine enverra ses messages vers la console et que certains Loggers journaliseront dans un fichier. Le Logger org.apache.catalina introduit une rupture dans l'additivité, seuls les Appenders définis à partir de son niveau seront affectés à ses descendants.

Quel que soit le format de la configuration, le procédé est toujours le même, seule la forme change. Il faut tout d'abord configurer les différents Appenders. Ensuite vient la configuration des Loggers. Vous n'êtes bien sûr pas obligé de configurer tous les Loggers de façon individuelle, utilisez les mécanismes d'héritage de niveau et d'Appender. Le minimum requis pour que Log4j fonctionne correctement est d'attribuer un Appender correctement configuré au Logger racine.

Si log4j n'est pas correctement configuré, cela n'empêchera pas l'application de fonctionner, simplement, les messages de journalisation peuvent être perdus.

La configuration de log4j peut se faire via un fichier properties classique (clé=valeur(s)) ou un fichier XML. La seconde solution offre plus de possibilités et, de par son format, est plus structurée ce qui permet de s'y retrouver plus facilement. Une troisième méthode est de configurer le système de journalisation par programmation, mais nous n'en parlerons pas ici en raison de son manque de flexibilité. Notez toutefois que si vous procédez de cette façon, vous devez appeler la méthode activateOptions() de chaque Appender une fois que vous lui avez fourni tous ses paramètres.

Pour déterminer le fichier de configuration ainsi que son format, log4j utilise le mécanisme de recherche suivant. La recherche des fichiers s'effectue via le ClassLoader, les fichiers de configuration doivent donc se trouver sur le classpath.

• Si la propriété système log4j.defaultInitOverride est définie à autre chose que false, le mécanisme de recherche n'est pas exécuté (à utiliser si vous configurez le système par programmation).
• Vous pouvez définir les propriétés système log4j.configuration et log4j.configuratorClass qui indiquent respectivement le fichier à utiliser et la classe servant à lire et à charger les propriétés (elle doit implémenter l'interface org.apache.log4j.spi.Configurator).
• En l'absence de propriété système indiquant le fichier à utiliser, log4j recherche un fichier nommé log4j.xml, si celui-ci n'existe pas, il tente d'obtenir le fichier log4j.properties. Quel que soit le cas (fichier de configuration personnalisé ou mécanisme de recherche), si le fichier est introuvable, le mécanisme est interrompu et log4j n'est pas configuré.
• Si aucun Configurator n'est spécifié et que le fichier termine par l'extension .xml, log4j utilise un DomConfigurator (configuration XML), si l'instanciation est impossible (classe inexistante, qui n'implémente pas Configurator, etc.), le mécanisme est interrompu et log4j n'est pas configuré. Si aucune classe n'est précisée et que le fichier n'est pas un fichier XML, un PropertiyConfigurator (configuration classique) est utilisé.

La méthode la plus simple consiste donc à laisser faire log4j en plaçant un fichier log4j.xml dans un répertoire situé sur le classpath.

La configuration via des fichiers properties est la première à avoir été implémentée, sa structuration est basique et ses possibilités sont plus restreintes que celles des fichiers XML (certains Appenders ne peuvent pas être configurés via un fichier properties). Néanmoins, il est utile de connaître son organisation puisqu'elle reste très répandue.

L'ordre de configuration présenté ici (Appenders puis Loggers) est purement arbitraire (elle suit en fait l'ordre utilisé dans la DTD des fichiers XML), vous pouvez faire l'inverse ou même mélanger les deux, log4j s'y retrouve parfaitement.

Vous pouvez définir un niveau minimal pour tous les Loggers au moyen de la clé log4j.threshold. Cela signifie que tous les messages en dessous de ce niveau seront ignorés par tous les Loggers quel que soit leur niveau (mais les messages au-dessus de ce niveau sont traités normalement, en fonction du niveau de chaque Logger).

Si vous voulez que log4j affiche des messages de débogage indiquant les opérations effectuées en interne, vous pouvez positionner à true la clé log4j.debug. Cela peut être utile lors de la mise au point d'une configuration ou d'un Appender personnalisé.

III-2-2-1. Configuration des Appenders▲

log4j.appender.NomAppender=ClasseAppender

log4j.appender.AppenderLogFactor5=org.apache.log4j.lf5.LF5Appender

log4j.appender.NomAppender.NomOption=ValeurOption

log4j.appender.Console=org.apache.log4j.ConsoleAppender
log4j.appender.Console.layout=org.apache.log4j.SimpleLayout

III-2-2-2. Configuration des Loggers▲

log4j.logger.nom.du.logger=[niveau], appender1, appender2

log4j.additivity.nom.du.logger=true|false

log4j.logger.com.developpez.beuss.java.log4j.MonLogger=INFO, UnAppender

log4j.logger.com.developpez.beuss.java.log4j=, UnAppender

log4j.logger.rootLogger=INFO, UnAppender

Comme nous l'avons déjà vu, les fichiers XML sont beaucoup plus structurants que les fichiers properties. Ils obligent à une certaine disposition des différents éléments puisque le fichier de configuration XML est validé vis-à-vis de sa DTD lorsqu'il est chargé. La structure (simplifiée) d'un fichier de configuration log4j au format XML est la suivante :

• configuration des Appenders ;
• configuration des Loggers ;
• configuration du Logger racine.

Les différentes parties de la configuration sont détaillées dans les sections suivantes. La syntaxe globale du fichier de configuration est la suivante :

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" [threshold="all"] [debug="false"]>
    <!-- Déclaration des différents Appenders et Loggers -->
</log4j:configuration>

Les propriétés threshold et debug sont identiques aux clés correspondantes dans la configuration via un fichier properties, elles permettent respectivement d'indiquer le niveau minimum que doit avoir un message pour être transmis aux Loggers et de demander à log4j d'afficher des informations sur le déroulement des opérations.

III-2-3-1. Configuration des Appenders▲

<appender name="NomAppender" class="ClasseImplementation">
     [<param name="ParamètreAppender1" value="ValeurParamètreAppender1"/>]
     [<layout class="ClasseLayout"<
         [<param name="ParamètreLayout1" value="ValeurParamètreAppender1"/>]
     </layout>]
 </appender>

<appender name="console" class="org.apache.log4j.ConsoleAppender">
     <layout class="org.apache.log4j.SimpleLayout"/>
 </appender>

III-2-3-2. Configuration des Loggers▲

<logger name="nomLogger" [additivity="false"]>
     [<level value="NomLevel"/>]
     [<appender-ref ref="NomAppender1"/>]
 </logger>

Comme nous l'avons vu lors de l', il est possible de définir un seuil au niveau de l'Appender en dessous duquel les messages ne seront pas journalisés. Il vient en complément du seuil global et du niveau propre du chaque Logger. Ce seuil est positionnable via la propriété threshold :

<appender name="console" class="org.apache.log4j.ConsoleAppender">
     <param name="threshold" value="INFO"/>
     <layout class="org.apache.log4j.PatternLayout">
         <param name="ConversionPattern" value="%-5p %c{1} - %m%n" />
     </layout>
 </appender>

Ce paramètre est pratique lorsque l'on veut que l'Appender ne prenne en compte que les messages au-dessus d'un certain niveau. Néanmoins, il peut être souhaitable de réellement séparer les différents niveaux pour, par exemple, avoir un fichier contenant les messages de débogage, un autre les messages d'information, etc. Dans ce cas, le paramètre threshold n'est plus suffisant. Pour cela, il faut utiliser un autre mécanisme de log4j : les filtres. Les filtres ne sont supportés que dans la configuration XML, ils se placent au sein de la balise appender. Dans notre cas, on peut utiliser le LevelMatchFiler ou le LevelRangeFilter selon que l'on veut ne journaliser que les messages d'un niveau donné ou ceux compris dans un intervalle de niveau. Voici un exemple de configuration :

<!-- Premier Appender, ne journalise que les messages DEBUG -->
 <appender name="filedebug" class="org.apache.log4j.FileAppender">
     <param name="file" value="debug.log"/>
     <layout class="org.apache.log4j.SimpleLayout"/>
     <filter class="org.apache.log4j.varia.LevelMatchFilter">
         <param name="levelToMatch" value="DEBUG"/>
     </filter>
     <filter class="org.apache.log4j.varia.DenyAllFilter"/>
 </appender>
 <!-- Second Appender, ne journalise que les messages INFO à ERROR (exclu donc FATAL) -->
 <appender name="fileinfoup" class="org.apache.log4j.FileAppender">
     <param name="file" value="infoup.log"/>
     <layout class="org.apache.log4j.SimpleLayout"/>
     <filter class="org.apache.log4j.varia.LevelRangeFilter">
         <param name="levelMin" value="INFO"/>
         <param name="levelMax" value="ERROR"/>
     </filter>
 </appender>
 <root>
     <appender-ref ref="filedebug" />
     <appender-ref ref="fileinfoup"/>
 </root>

Le LevelMatchFilter prend comme paramètre levelToMatch qui est le niveau auquel doit correspondre le message pour ne pas être rejeté (on peut éventuellement lui passer acceptOnMatch avec la valeur false pour qu'au contraire le message soit rejeté). Il est nécessaire d'appliquer un second filtre qui rejette tous les messages qu'il rencontre. C'est dû au comportement du LevelMatchFilter : si le niveau du message correspond au niveau défini, le message est accepté sans passer par les autres filtres. Par contre, si le niveau ne correspond pas, le filtre est dit neutre, c'est-à-dire qu'il laisse le soin aux filtres suivants de décider ; s'il n'y a pas d'autres filtres, le message est accepté ce qui n'est pas le comportement attendu dans notre exemple.

Le second Appender est configuré pour accepter les messages de INFO à ERROR (inclus), grâce à un LevelRangeFilter qui prend en paramètre levelMin (niveau minimum que le message doit avoir pour être accepté) et levelMax (niveau maximum que le message peut avoir pour être accepté). Ce filtre accepte lui aussi un paramètre acceptOnMatch, mais celui-ci a une sémantique un peu différente du LevelMatchFilter : s'il est positionné à false le filtre rejette le message s'il est à l'extérieur des bornes et reste neutre s'il est à l'intérieur ; si acceptOnMatch est à true (par défaut) les autres filtres ne sont pas consultés et le message est accepté directement s'il est dans l'intervalle.

Les filtres sont des outils très puissants, cependant, il est recommandé d'utiliser en priorité les mécanismes de filtrage des Loggers et des Appenders avant d'y avoir recours.

Le ConsoleAppender journalise, comme son nom l'indique, vers la console. Il est cependant possible de choisir si les messages sont envoyés vers la sortie standard ou vers la sortie des erreurs. Ce comportement est contrôlé par le paramètre target qui prend les valeurs System.out (sortie standard) ou System.err (sortie des erreurs).

Le FileAppender est la classe de base pour tous les Appenders de type RollingFile, les propriétés décrites dans cette section s'appliquent donc également à ces Appenders. Notez que certaines propriétés proviennent en fait du WriterAppender.

• append : indique si l'écriture doit se faire à la suite dans le fichier (true, valeur par défaut) ou si le contenu doit être écrasé (false) ;
• encoding : définit l'encodage du fichier produit (utilisation des propriétés système si aucun encodage n'est précisé) ;
• bufferedIO : indique si un tampon doit être utilisé pour l'écriture (false par défaut) ;
• bufferSize : dans le cas où un tampon est utilisé pour la sortie, indique la taille du buffer en octets (8Ko par défaut) ;
• file : définit le nom de base du fichier où effectuer la journalisation (des suffixes peuvent y être ajoutés dans le cas des RollingFileAppenders).

Le JDBCAppender enregistre les messages de journalisation dans une base de données. Il est donc nécessaire de lui fournir les informations nécessaires à cette insertion :

• driver : indique le Driver JDBC à utiliser pour la connexion ;
• url : URL JDBC utilisée pour se connecter à la base ;
• user, password : nom d'utilisateur et mot de passe (propriétés distinctes), l'utilisateur doit avoir le droit d'insérer de nouvelles lignes ;
• bufferSize : nombre d'événements de journalisation à recevoir avant de les envoyer en base ;
• sql : requête d'insertion à utiliser, elle suit le format du , par exemple « INSERT INTO journal(niveau, logger, message) VALUES('%p', '%c', '%m'); ».

Le paramètre important de cet Appender est datePattern, en effet, c'est lui qui va contrôler la fréquence du roll-over du fichier journal ; il détermine également le modèle du nom de fichier. Le motif utilisé suit les conventions de SimpleDateFormat, la précision va jusqu'à la minute (c'est-à-dire que le fichier est sauvegardé et renommé toutes les minutes). Consultez la Javadoc de DailyRollingFileAppender pour des exemples et une description de l'interprétation du format.

Les RollingFileAppender utilisent un jeu de fichiers tournants pour effectuer leur journalisation. C'est-à-dire que lorsque le roll-over intervient, soit parce que le fichier atteint une certaine taille (RollingFileAppender) soit parce que cela a été demandé (ExternallyRolledFileAppender), le fichier journal courant est archivé en nomdefichier.1 tandis que l'indice des autres archives est incrémenté de 1. Si le suffixe fichier le plus ancien dépasse une certaine valeur, celui-ci est supprimé.

Les éléments configurables dans ce mécanisme sont l'indice maximal des fichiers de sauvegarde (par le biais de la propriété maxBackupIndex) et, uniquement pour le RollingFileAppender, la taille du fichier déclenchant le roll-over (via la propriété maxFileSize).

Le déclenchement du roll-over pour l'ExternallyRolledFileAppender se fait d'une façon similaire à la suivante :

Socket sock = new Socket([Adresse où tourne l'Appender], [port sur lequel écoute l'Appender]);
 DataOutputStream dos = new DataOutputStream(sock.getOutputStream());
 dos.writeUTF("RollOver");
 dos.close();
 sock.close();

Le port sur lequel écoute l'ExternallyRolledFileAppender est configurable via la propriété port (tout simplement), mais la chaîne déclenchant le roll-over ne l'est pas. Notez que la casse est prise en compte, si l'Appender reçoit autre chose que « RollOver », il renverra un message d'erreur via le Socket.

L'AsyncAppender fait suivre les messages aux Appenders qui lui sont attachés dans un Thread distinct. Cela permet de ne pas bloquer l'application effectuant la journalisation. Les événements sont journalisés un par un au fur et à mesure. Lorsque la file est pleine, l'AsyncAppender doit attendre qu'une place se libère avant de pouvoir continuer. Il n'est configurable que par un fichier XML.

Tout d'abord, il faut lui indiquer les Appenders auxquels il va devoir faire suivre les événements. Il ne s'agit pas à proprement parler de propriétés puisque ce sont les Appenders proprement dits qui sont utilisés et non pas une valeur quelconque. Aussi, il existe une balise spéciale : appender-ref. Celle-ci dispose d'un attribut ref qui doit prendre pour valeur le nom d'un Appender. Il est possible d'affecter plusieurs Appenders à un AsyncAppender.

Ensuite, il est possible de spécifier la taille de la file d'attente des messages. Dans une application envoyant beaucoup de messages à des Appenders assez lents, il peut être utile d'augmenter sa taille. Cela se fait via la propriété bufferSize (128 événements par défaut). Enfin, si vos Appenders affichent les informations sur l'endroit dans le code d'où est émis le message, il est utile de positionner la propriété locationInfos à true.

<appender class="org.apache.log4j.FileAppender" name="file">
    <param name="file" value="extern.log"/>
    <layout class="org.apache.log4j.SimpleLayout"/>        
</appender>

<appender class="org.apache.log4j.AsyncAppender" name="async">
    <appender-ref ref="file"/>
</appender>

Le PatternLayout est le Layout le plus souple et le plus configurable. Comme son nom l'indique, il utilise un motif pour mettre en forme les informations fournies par l'événement de journalisation. Sa seule propriété se nomme conversionPattern, elle permet d'indiquer la façon dont doivent être formatées les informations. Ce formatage s'effectue au moyen de séquences d'échappement. En voici quelques-unes :

• %c : nom du logger ;
• %m : message de journalisation ;
• %n : caractère de nouvelle ligne spécifique à la plate-forme. N'oubliez pas de l'ajouter à la fin de la ligne ;
• %p : niveau de gravité de l'événement.

Il est possible de contrôler l'alignement des différentes informations au moyen de chiffres placés entre le signe % et la lettre indiquant l'information à afficher. Reportez-vous à la JavaDoc pour plus d'informations. Ce Layout est celui utilisé entre autres par le JDBCAppender pour la définition de la requête SQL.

Les Layouts HTMLLayout et XMLLayout ont un paramètre en commun appelé locationInfo qui sert à demander au Layout d'inclure des informations sur la provenance du message dans le code. Le HTMLLayout indiquera le fichier et la ligne d'où provient le message tandis que le XMLLayout inclura également les noms de la classe et de la méthode.

Le HTMLLayout accepte aussi un paramètre title indiquant le titre que doit porter la page récapitulant les informations.