Log4perl

Si ce bandeau n'est plus pertinent, retirez-le. Cliquez ici pour en savoir plus.

Cet article sur l'informatique doit être recyclé (janvier 2007).

Une réorganisation et une clarification du contenu paraissent nécessaires. Améliorez-le, discutez des points à améliorer ou précisez les sections à recycler en utilisant {{section à recycler}}.

Log4perl est un projet open source qui est une implémentation en Perl du paquetage Log4j. Il permet de gérer proprement la journalisation des actions effectuées via Perl.

Les utilisateurs ayant déjà utilisé des systèmes de journalisation sont familiers avec la notion de niveau de journalisation ou de priorité d'un message. Il s'agit d'une entité représentant l'importance du message à journaliser (FATAL, ERROR, WARN, INFO et DEBUG). Log4perl se base sur un mécanisme très puissant et flexible. Il permet de lancer ou arrêter les Logs à tout moment, il suffit d’indiquer le niveau du détail et le relier au sous-système qui est actuellement exécuté.

Log::Log4perl est différent des systèmes de journalisation traditionnel comme le debug, Il permet de commander le nombre des Logs produits en trois niveaux différents :

À un endroit central dans votre système (dans un fichier de configuration ou dans le code de démarrage) ou vous indiquez l’élément (classes, fonctions) qui devrait générer les Logs.
Le niveau de Log de l’élément.
L’appender à alimenter pour les Logs (écran, fichier de Logs, courriel …), ainsi que le format d’affichage des messages des Logs.

Objet du document[modifier | modifier le code]

Ce document est un résumé des spécifications de log4perl. C'est un « document vivant », soutenu au fur et à mesure que de nouvelles versions de log4perl voient le jour.

Bien que nous sachions qu'elles seront légèrement dépassées au moment où vous lirez ce document, nous avons inclus ces spécifications de développement car il s'agit d'une source de référence et que nous pensons que ce document serait incomplet sans elles. vous pouvez consulter la documentation en ligne de la version de log4perl que vous avez installée.

Syntaxe[modifier | modifier le code]

 # Easy mode : simple ...
 use Log::Log4perl qw(:easy);
 Log::Log4perl->easy_init($ERROR);
 DEBUG "This doesn't go anywhere";
 ERROR "This gets logged";
 # ... or standard mode for more features:
 Log::Log4perl::init('/etc/log4perl.conf');
  --or--
 # Check config every 10 secs
 Log::Log4perl::init_and_watch('/etc/log4perl.conf',10);
 --then--
 $logger =Log::Log4perl->get_logger('house.bedrm.desk.topdrwr');
 $logger->debug('debug message');
 $logger->info('info message');
 $logger->warn('etc');
 $logger->error('..');
 $logger->fatal('..');

 #####/etc/log4perl.conf###############################
 log4perl.logger.house = WARN,  FileAppndr1
 log4perl.logger.house.bedroom.desk = DEBUG, FileAppndr1
 log4perl.appender.FileAppndr1 = Log::Log4perl::Appender::File
 log4perl.appender.FileAppndr1.filename = desk.log 
 log4perl.appender.FileAppndr1.layout = Log::Log4perl::Layout::SimpleLayout

######################################################
=head1 ABSTRACT
Log::Log4perl provides a powerful logging API for your application

Obtenir de l'aide[modifier | modifier le code]

Si vous avez des questions sur Log4perl, vous pouvez obtenir de l'aide sur la liste de diffusion log4perl-devel@lists.sourceforge.net .

Il est également judicieux de consulter la page de documentation de Log4perl à : http://log4perl.sourceforge.net/releases/Log-Log4perl/docs/html/Log/Log4perl.html Avant de poser une question, quelle qu'elle soit, relisez ce document, consultez les archives et lisez la FAQ de Log4perl.

Notations et conventions[modifier | modifier le code]

Les conventions suivantes s'appliquent à ce document : $log Objet descripteur du logger.

Principe d'utilisation[modifier | modifier le code]

Chargement du module[modifier | modifier le code]

Pour utiliser Log4perl, il faut d'abord charger le module Log::Log4perl: use Log::Log4perl;

Fichier de Configuration[modifier | modifier le code]

Puis, vous pouvez instancier le Logger en utilisant des commandes perl ou par un fichier de configuration. Le fichier de configuration peut ressembler à :

# Un simple logger avec Log::Log4perl::Appender::File 
# Fichier appender en Perl
log4perl.logger= ERROR, fichier_log

# paramétrage de l'appender "logger_batch" :
log4perl.appender.fichier_log=Log::Log4perl::Appender::File
log4perl.appender.fichier_log.filename=/usr2/projets/tmp/ins/ins.log
log4perl.appender.fichier_log.mode=append
log4perl.appender.fichier_log.max=5
log4perl.appender.fichier_log.layout=Log::Log4perl::Layout::PatternLayout
log4perl.appender.fichier_log.layout.ConversionPattern=%d{yyyy-MM-dd  HH:mm:ss,SSS} %P %-5p> %F{1}:%L %M - %m%n

Ces lignes permettent de définir un standard logger qui journalise les erreurs dans le fichier inscription.properties en utilisant le format : Date heure:minute:seconde, milliseconde pid du processus niveau du message de log> nom du fichier source:numéro de la ligne classe fonction - message (retour ligne).

Exemple :

2007-01-03 18:10:53,854 part-dev INFO > IAMGEN_Utilitaires.pm:140 IAMGEN::log_comment – message

Initialisation du logger[modifier | modifier le code]

En supposant que le fichier de configuration se trouve sous inscription.properties, vous pouvez le lire au début de code perl en utilisant : Log::Log4perl→init("inscription.properties");

Utilisation du logger[modifier | modifier le code]

Après que l’initilisation soit faite quelque part dans le code, vous pouvez utiliser les objets loggers dans le code. Noter qu'il n'y a aucun besoin de ne porter aucune référence du logger autour avec vos fonctions et méthodes. Vous pouvez obtenir un logger n'importe quand par l'intermédiaire d'un mécanisme de singleton, il suffit de faire appel à la méthode static du logger get_logger($category) pour obtenir une et une seule référence du logger avec une certaine catégorie.

Exemple:

package My::MegaPackage;
  use  Log::Log4perl;
   sub some_method {
       my($param) = @_;
       my $log = Log::Log4perl→get_logger("My::MegaPackage");
       $log→debug("Debug message");
       $log→info("Info message");
       $log→warn("Warning message");
       $log→error("Error message");
       ...
   }

En se fondant sur le fichier de configuration présenté précédemment, Log::Log4perl affichera que ‘Error message’ dans le fichier log spécifié /usr2/projets/tmp/ins/ins.log car le niveau des log a été initialisé à Error dans le fichier de configuration.

Niveau de journalisation[modifier | modifier le code]

Le niveau de journalisation ou de priorité d'un message se base d'une entité représentant l'importance du message à journaliser, elle est représentée par la classe org.apache.log4j.Level. Un message n'est journalisé que si sa priorité est supérieure ou égale à la priorité du Logger effectuant la journalisation. Log4j définit 5 niveaux de logging présentés ici par gravité décroissante.

FATAL: Utilisé pour journaliser une erreur grave pouvant mener à l'arrêt prématuré de l'application.
ERROR: Utilisé pour journaliser une erreur qui n'empêche cependant pas l'application de fonctionner.
WARN: Utilisé pour journaliser un avertissement, il peut s'agir par exemple d'une incohérence dans la configuration, l'application peut continuer à fonctionner mais pas forcément de la façon attendue.
INFO: Utilisé pour journaliser des messages à caractère informatif (nom des fichiers, etc.).
DEBUG: Utilisé pour générer des messages pouvant être utiles au débogage.

Si vous configurez un système de journalisation avec un niveau warning alors tous les messages journalisés avec info() et debug() seront ignorés alors que fatal(), error() et warn() vont passer car leur priorité est supérieure ou égale au niveau configuré

Voir aussi syslog#Niveau de gravité.

Appenders[modifier | modifier le code]

Afin de mieux les manipuler, il est nécessaire de connaître le fonctionnement des Appenders et de configurer correctement Log4perl. Log::Log4perl ne définit aucun Appender par défaut. Les Appenders sont le moyen utilisé par log4perl pour enregistrer les événements de journalisation. Chaque Appender a une façon spécifique d'enregistrer ces événements. Les paramètres nécessaires à certains des Appenders sont détaillés dans la partie configuration. Cependant, il est possible d'affecter un niveau seuil (threshold) à tous les Appenders (ce qui est le cas de tous les Appenders fournis avec log4perl). Dans ce cas, un message n'est journalisé par un Appender donné que si son niveau est supérieur ou égal à celui du Logger et qu'il est supérieur ou égal au seuil de l'Appender considéré.

Log::Log4perl[modifier | modifier le code]

Log::Log4perl vient avec une série d'Appenders qu'il est utile de décrire, puisqu'ils seront repris dans la configuration :
Log::Log4perl::Appender::Screen → Effectue la journalisation vers la console ;

Log::Log4perl::Appender::ScreenColoredLevels
Log::Log4perl::Appender::File → Journalise dans un fichier ;
Log::Log4perl::Appender::Socket → Envoie les événements de journalisation vers un serveur de journalisation
Log::Log4perl::Appender::DBI → Effectue la journalisation vers une base de données ;
Log::Log4perl::Appender::Synchronized
Log::Log4perl::Appender::RRDs

CPAN[modifier | modifier le code]

Vous pouvez trouver dans CPAN d’autres Appenders comme

Log::Log4perl::Layout::XMLLayout
Log::Dispatch
Log4perl utilise l’excellent framework de Dave Rolskys Log::Dispatch qui implémente une variété d’Appenders :
Log::Dispatch::ApacheLog
Log::Dispatch::DBI
Log::Dispatch::Email,
Log::Dispatch::Email::MailSend,
Log::Dispatch::Email::MailSendmail,
Log::Dispatch::Email::MIMELite
Log::Dispatch::File
Log::Dispatch::FileRotate
Log::Dispatch::Handle
Log::Dispatch::Screen
Log::Dispatch::Syslog
Log::Dispatch::Tk

Configuration directe des Appenders dans le code[modifier | modifier le code]

En supposant que vous vouliez afficher des messages de Logs info ou d’une priorité supérieure pour une catégorie donnée (Toto::Test) dans l’écran et dans un fichier de configuration (test.log). Vous pouvez définir deux Appenders au début de votre code en vous basant sur les deux modules (Log::Log4perl::Appender::File et Log::Log4perl::Appender::Screen) :

use Log::Log4perl;
# Configuration 
 my $conf = q(
  log4perl.category.Toto.Test        = INFO, Logfile, Screen
  log4perl.appender.Logfile          = Log::Log4perl::Appender::File
  log4perl.appender.Logfile.filename = test.log
  log4perl.appender.Logfile.layout   = Log::Log4perl::Layout::PatternLayout
  log4perl.appender.Logfile.layout.ConversionPattern = [%r] %F %L %m%n
  log4perl.appender.Screen         = Log::Log4perl::Appender::Screen
  log4perl.appender.Screen.stderr  = 0
  log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout
 );

# Initialisation du Logger en passant la référence  
 Log::Log4perl::init( \$conf);

Formats des messages[modifier | modifier le code]

Lorsque les messages de journalisation sont récupérés par l’Appender dans le système de journalisation. Un format de présentation des messages est défini, on y trouve des données intéressantes comme la date, l’heure, le pid du processus niveau du message de log> nom du fichier ...

Comme pour Log4j, Log4perl fournit principalement deux Layouts pour mettre en forme les différents événements de journalisation Log::Log4perl::Layout::SimpleLayout et Log::Log4perl::Layout::PatternLayout

Log::Log4perl::SimpleLayout : Comme son nom l'indique, il s'agit du Layout le plus simple, les événements journalisés ont le format niveau – message (Retour à la ligne) .
Log::Log4perl::Layout::PatternLayout : permet de formater les événements d'à peu près n'importe quelle façon, le format du message est spécifié par un motif (pattern) composé de texte et de séquences d'échappement indiquant les informations à afficher.

%c catégorie d’événement de journalisation.
%C Nom complet du package (ou classes) de l’appelant
%d Date courante Format in yyyy/MM/dd hh:mm:ss
%F Fichier où l’événement de journalisation s’est produit
%H Hostname
%l Nom complet de la méthode où l’événement s’est produit, suivi par le nom du fichier source et le numéro de la ligne entre parenthèses
%L Numéro de la ligne ou fichier source où l’événement s’est produit
%m Message 
%M Méthode (ou fonction) où l’événement s’est produit
%n retour à la ligne
%p Priorité de l’événement
%P pid du processus en cours
%r Nombre de millisecondes écoulées entre le début du programme et jusqu’à la production de l’événement
%x NDC stack 
%X{clé} MDC 
%% signe littéral de pour cent (%)

Sinon, par défaut, les événements sont journalisés au format message (Retour à la ligne);

Remarques :
- Le format de la date peut être spécifique. par exemple %d{HH:mm} permet de n’afficher que les heures et les minutes
- Même remarque pour les fichiers, par exemple %F {1} permet de n’afficher que le nom de fichier sans le chemin d’accès
- %c{2} permet de n’afficher que les deux dernières composantes de la catégorie en cours. par exemple si la catégorie est Toto::Tata::Titi on aura affiché Tata::Titi

Référence[modifier | modifier le code]

Si ce bandeau n'est plus pertinent, retirez-le. Cliquez ici pour en savoir plus.

Certaines informations figurant dans cet article ou cette section devraient être mieux reliées aux sources mentionnées dans les sections « Bibliographie », « Sources » ou « Liens externes » (septembre 2008).

Vous pouvez améliorer la vérifiabilité en associant ces informations à des références à l'aide d'appels de notes.