Log4perl

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.

Si vous avez déjà utilisé des systèmes de journalisation, vous êtes 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 vos 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

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 consultez la documentation en ligne de la version de log4perl que vous avez installée.

Syntaxe

# 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

Si vous avez des questions sur Log4perl, vous pouvez obtenir de l'aide sur la liste de diffusion [e-mail] .

Il est également judicieux de consulter la page de documentation de 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

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

Principe d'utilisation

Chargement du module

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

Fichier de Configuration

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

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

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 appelle à 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

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

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

• 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

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 direct des Appenders dans le code

En supposant que vous voulez afficher des messages de Logs info ou d’une priorité supérieur 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 debut de votre code en se 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

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 ou l’événement de journalisation s’est produit
%H Hostname
%l Nom complet du de la méthode ou l’événement s’est produit, suivit 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 ou l’événement s’est produit
%m Message 
%M Méthode (ou fonction) ou l’evenement s’est produit
%n retour à la ligne
%p Priorité de l’événement
%P pid du processus en cours
%r Nombre de millisecondes écoulé entre le début du programme et jusqu’à la production de l’événement
%x NDC stack 
%X{clé} MDC 
%% signe littéral de pourcent (%) 

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 d’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

• http://logging.apache.org/log4j/docs/
• http://cpan.uwinnipeg.ca/htdocs/Log-Log4perl/Log/Log4perl.html
• http://cpan.org/

Voir aussi

Documentation

• http://search.cpan.org/
• http://cpan.org/
• http://language.perl.com/style/
• http://cpan.uwinnipeg.ca

Livres et revues

• Introduction à Perl, 3e Édition (Broché) de Randal L. Schwartz, Tom Phoenix
• Perl en action (Broché) de Christiansen

Foire Aux Questions (FAQ)

http://perl.enstimac.fr/perl5.6.1/Log/Log4perl/FAQ.html