Introduction

OrnithoLog est un framework de logging, dont le but est de mettre à disposition un système simple pour gérer les messages d’erreur et comprendre le flux d’exécution d’un programme.

API

Récupération d'un objet Logger

Les objets Logger sont associé à la classe qui va les utiliser, il y a donc un objet Logger par classe qui produit des logs. Cela permet de pouvoir mieux configurer la façon dont les logs sont formattés et enregistrés.

Pour récupérer l'objet Logger associés à une classe, il faut faire appel à la méthode statique getLogger de la classe LoggerFactory, en lui passant en paramètre le nom de la classe appelante. Exemple:

                                    
Logger logger = LoggerFactory.getLogger(this.getClass().getName());
                                

Si le logger associé à la classe appelante existe déjà, le LoggerFactory.getLogger()va le retourner, et s'il n'existe pas, il sera crée.

Niveau des logs

Notre framework distingue 4 niveaux de log et présente une hiérarchie :

• ERROR : Au niveau le plus haut, cette configuration enregistre les logs d'erreur.
• WARN : En dessous, cette configuration enregistre les logs d'avertissement et d'erreur.
• INFO : Encore en-dessous, cette configuration enregistre les logs d'information, d'avertissement et d'erreur.
• DEBUG : Enfin, cette dernière configuration enregistre les logs de débogage, d'information, d'avertissement et d'erreur. Valeur par défaut.

Pour logguer un message, il faut faire appel à la méthode .debug("message"), .info("message"), .warn("message") ou .error("message") de l'instance Logger.

Le message peut bien contenir des variables à afficher et le fonctionnement est similaire à l'appel de System.out.println().

Exemple:

                                    
Logger logger = LoggerFactory.getLogger(this.getClass().getName());
logger.info("ceci est un message informatif");  // sera enregistré car le niveau de log par défaut est DEBUG
logger.setLevel(LogLevel.WARN);             // on change le niveau de filtrage des logs à WARN
logger.debug("ceci est message de debug");  // ne sera pas enregistré car on n'affiche que les messages de niveau WARN ou supérieur
logger.error("ceci est un message s'erreur");  // sera enregistré car ERROR est encore plus important que WARN
                                

Format des logs

Loggueurs fournis avec le Framework

Notre framework est livré avec 3 formatteurs de logs, disponibles dans le package com.github.encrypt.ornitholog.formatters :

• DateFormatter : Ce formatteur renvoie la date courante du système afin d'avoir des logs datés.
• LevelFormatter : Ce formatteur renvoie le niveau actuel du loggueur passé en paramètre.
• ClassFormatter : Ce formatteur renvoie la classe du loggueur passé en paramètre.

Créer un nouveau formatteur

Vous êtes libres de créer un nouveau formatteur ! Pour cela, il suffit de créer une classe héritant de LogFormatter et de lui donner le comportement désiré.

Vérifiant l'Open-Closed Principle, il est aisé d'ajouter des fonctionnalités au framework.

Faire appel aux formatteurs

Le formattage des logs a été pensé suivant le design pattern "Decorator".

Pour faire appel aux formatteurs, il faut donc les chaîner en les imbriquants les uns dans les autres.

Exemple d'appel :

                                        
Logger logger = LoggerFactory.getLogger("MaClasse");
logger.setFormatter(new DateFormatter(new LevelFormatter(new ClassFormatter())));
                                    

Cible des logs

Un même message peut donner lieu à plusieurs cibles et trois sont fournies avec ce framework.

Toutes les cibles héritent de la classe LogTarget et suivant le principe OCP il est donc facile d'ajouter vos propres cibles.

Console

La première cible fournie est la console, qui est un niveau basique.

Son utilisation est simple, il n'y a aucun paramètre à lui passer.

Exemple :

                                        
Logger logger = LoggerFactory.getLogger("MaClasse");
logger.addTarget(new LogToConsole());
                                    

Fichier plat

Une autre cible fournie est l'écriture des logs dans un fichier plat.

Pour l'utiliser, il faut faire appel à LogToFile en passant en paramètre le chemin vers le fichier d'enregistrement.

Cette cible possède également la méthode setTargetFile(String targetFile) permettant de créer l'objet LogToFile sans lui passer de chemin dans un premier temps.

Exemple :

                                        
Logger logger = LoggerFactory.getLogger("MaClasse");

LogToFile myTarget = new LogToFile();
myTarget.setTargetFile("/path/to/my/file");
logger.addTarget(myTarget);

-- OU --

logger.addTarget(new LogToFile("/path/to/my/file"));
                                    

Fichier rotatif

Enfin, la dernière cible fournie permet l'écriture des logs dans un fichier rotatif.

Son mode de fonctionnement est similaire à celui du fichier plat, hormis le fait que son constructeur prend en second paramètre la taille cible maximale, en octets.

En plus de la méthode setTargetFile(String targetFile), la méthode setMaxFileSize(double maxFileSize) vous permet de spécifier la taille maximale du fichier cible ultérieurement.

Exemple :

                                        
Logger logger = LoggerFactory.getLogger("MaClasse");

LogToRotatingFile myTarget = new LogToRotatingFile("/path/to/my/file", 1024000.0);
myTarget.setTargetFile("/path/to/my/file");
myTarget.setMaxFileSize(1024000.0);
logger.addTarget(myTarget);

-- OU --

logger.addTarget(new LogToRotatingFile("/path/to/my/file", 1024000.0));
                                    

Configuration des Loggers

Méthodes fournies

Plusieurs méthodes sont fournies pour configurer les instances de Logger :

• addTarget(LogTarget target): Permet d'ajouter une cible de logging.
• setFormatter(LogFormatter formatter): Permet de spécifier le formattage des logs en suivant le design pattern "Decorator".
• setLevel(LogLevel level): Permet de définir le niveau de logs du Logger.
• getLevel(): Permet de récupérer le niveau d'alerte du Logger.

Fichier .properties

Afin de créer automatiquement les instances de Logger et ne plus avoir à paramétrer une instance manuellement, il est possible de renseigner ses paramètres dans un fichier .properties, à mettre à la racine du projet utilisant le framework.

Pour ce faire, les paramètres doivent être sous la forme suivante : package.class:attribute = valeur.

• package.class: le nom de la classe à laquelle est affecté le Logger
• attribute: l'attribut auquel on veut affecter une valeur
• valeur: la valeur que l'on va affecter à l'attribut

Remarque: il est possible d'affecter des valeurs aà des attributs d'attributs, par exemple: package.class:attribute1.attribute2 = valeur.

Exemple de configuration :

com.myProject.MyClass:level = DEBUG
com.myProject.MyClass:formatter = DateFormatter
com.myProject.MyClass:target1 = LogToConsole
com.myProject.MyClass:target2 = LogToFile
com.myProject.MyClass:target2.path = "path/to/my/file"
com.myProject.MyClass:target3 = LogToRotatingFile
com.myProject.MyClass:target3.path = "path/to/my/other/file"
com.myProject.MyClass:target3.maxSize = 102400.0
                                

Prise en main

Export en .jar

Tout d'abord, cloner le projet en effetuant la commande : git clone https://github.com/Encrypt/Framework_logs.git

Ensuite, importer ce projet dans Eclipse en allant dans File > Import > General > Existing project into workspace et sélectionner le dossier du projet Ornitholog cloné.

Générer alors le projet en faisant clic droit sur le projet > Export > Java > JAR File puis enregistrer le JAR dans un dossier du système.

Utilisation

Pour utiliser le framework, une fois exporté en .jar, faire un clic droit > Properties > Java Build Path > Add external Jar puis sélmectionner le JAR qui a été exporté à l'étape précédente.

Normalement, toutes les classes du frameworks devraient alors être présentes et utilisables.

Diagramme UML

Credits

Licence

Nous livrons ce framework sous licence GPL.

Vous êtes libre de modifier, copier et redistribuer ce programme.

Plus d'informations sur la licence à l'adresse : http://www.gnu.org/licenses/

Auteurs

• Vincent Marquet
• Patrick Pereira Almeida
• Yann Privé

Étudiants à l'ESIEA Paris en 4A, année 2014/2015.