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.
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.
Notre framework distingue 4 niveaux de log et présente une hiérarchie :
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
Notre framework est livré avec 3 formatteurs de logs, disponibles dans le package com.github.encrypt.ornitholog.formatters
:
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.
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())));
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.
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());
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"));
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));
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.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 Loggerattribute
: l'attribut auquel on veut affecter une valeurvaleur
: la valeur que l'on va affecter à l'attributRemarque: 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
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.
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.
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/
Étudiants à l'ESIEA Paris en 4A, année 2014/2015.