# 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.
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

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.

## Obtenir de l'aide

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

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

### 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 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:
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 directe des Appenders dans 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) :

## 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.
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