API Logging. Journalisation des évènements. Conserver sur un support sûr des événements survenus dans un système ou une application

Transcription

1 API Logging Journalisation des évènements Philippe GENOUD UJF Janvier Journalisation Conserver sur un support sûr des événements survenus dans un système ou une application Un ou plusieurs fichiers journaux (log files) générés en cours d'exécution enregistrent des informations sur le déroulement de l'application. Nature de l'événement Date et heure Gravité Utilisateur. Utilisés pour : Produire des statistiques sur utilisation du système (ex: log du serveur Apache) Détecter des problèmes d'exécution Reprise après pane Philippe GENOUD UJF Novembre

2 Api java.util.logging Java depuis la version 1.4 propose une API standard pour journaliser les événements. Définie dans le package java.util.logging D'usage simple Permet de journaliser des événements dans un fichier au format texte ou XML Différents niveaux de sévérité applicables aux messages journalisés API conçue pour rendre les opérations de logging le moins coûteuses possible Possibilité de changer dynamiquement quels niveaux de messages sont journalisés Permet de faire des logging détaillés lorsque nécessaire tout en minimisant l'impact sur l'application en mode normal Extensible Philippe GENOUD UJF Novembre Api java.util.logging Principale classes de l'apijava.util.logging Génère log messages LogManager Object Associés aux handlers pour formater les LogRecords Logger LogRecord Handler Destination pour les LogRecords Formatter Encapsule contenu d'un log message MemoryHandler StreamHandler SimpleFormatter XMLFormatter ConsoleHandler FileHandler SocketHandler <interface> Filter Philippe GENOUD UJF Novembre

3 Principes généraux de l'api Logging Filter Formatter 1 Application 2 À un Logger peuvent être associés plusieurs handlers Logger 4 Handler Handler 7 Monde extérieur Fichier Console Socket Filter Filter Formatter 1 L'application demande à un Logger d'enregistrer une information dans le journal 2 Le Logger crée un objet LogRecord qui représente cette demande 3 Le Logger transmet éventuellement le LogRecord à un filtre pour décider si il doit être traité ou non 4 Si le filtre autorise son traitement le LogRecord est transmis à un Handler. 5 Le Handler transmet éventuellement le LogRecord à un filtre pour décider si il doit être traité ou non 6 Si le filtre autorise son traitement le LogRecord est transmis à un Formatter qui se charge de sa mise en forme et de son éventuelle localisation 7 Le Handler publie lerésultat produit par le Formatter sur un flux d'entrée/sortie Philippe GENOUD UJF Novembre Création d'un journal Journal représenté par un objet instance de la classe Logger Doit être créé qu'une seule fois et partagé par les instances des différentes classes de l'application Accès au journal dans une classe Référence statique pour accéder au journal private static Logger logger = Logger.getLogger("monLogger"); Nom du journal Méthode statique de la classe Logger. si plusieurs classes appellent getlogger() avec le même nom, le journal est créé au premier appel ; pour les prochains appels le journal n'est pas recréé, seule sa référence est retournée. Philippe GENOUD UJF Novembre

4 Création d'un journal Une fois le journal (Logger) créé il faut l'associer à un ou plusieurs handlers qui géreront les messages (LoggerRecords) Pour rediriger les messages du logger vers un fichier on utilise un objet FileHandler Création d'un file Handler qui redirigera les LoggerRecords vers vers le fichier mylog.log Handler fh = new FileHandler("myLog.log"); Plusieurs constructeurs permettent de spécifier le ou les fichiers utilisés et la manière dont ils le sont. Handler fh = new FileHandler(); Système choisit lui-même le nom du fichier Handler fh = new FileHandler("myLog.log", true); Le fichier est repris tel quel (true) ou recrée (false) Handler fh = new FileHandler("myLog.log", 5000, 4); Le journal est divisé en 4 fichiers de 5000 octets, utilisés de manière cyclique,de nom mylog.log.i avec i de 0 à 3 (motif par défaut) logger.addhandler(fh); Associe le FileHanlder au logger Philippe GENOUD UJF Novembre Création d'un journal public FileHandler(String pattern,int limit,int count, boolean append) pattern : motif du nom du fichier ou des fichiers à créer limit : nombre maximum d'octets pouvant être écrits dans le fichier (0 pour pas de limite). Si cette limite est dépassée, le FileHandler ferme le fichier, le renomme et débute un nouveau fichier de log avec le nom original count : nombre de fichiers à utiliser append : le fichier est repris tel quel (true) ou recrée (false) Lorsque ces arguments ne sont pas spécifiés dans le constructeur, une valeur par défaut définie par le LogManager est utilisée. pattern : %h/java%u.log limit : 0 count : 1 append : false Philippe GENOUD UJF Novembre

5 Création du journal Des caractères spéciaux peuvent être utilisés pour définir le nom du (des) fichier(s) de log Caractère / %h %t %u %g %% Signification Séparateur de répertoire pour la plateforme Répertoire de connexion de l'utilisateur (équivalent de la propriété système "user.home") Répertoire temporaire du système Un nombre unique utilisé pour distinguer le fichier log d'autres fichiers log qui auraient le même motif Le nombre généré automatiquement pour la rotation cyclique des fichiers quand limit non nul et count > 1 '%' Exemple Handler fh = new FileHandler("%h/myApps.%g.log", 5000, 3); 3 fichiers logs dans le "homedir" de l'utilisateur nommés myapps.0.log, myapps.1.log et myapps.2.log Philippe GENOUD UJF Novembre Ecriture d'un message Pour poster un message dans le journal on utilise la méthode log() de l'objet Logger. public void log(level level, String msg) Niveau du message. Si le logger est activé pour ce niveau le message est dirigé vers tous les handlers associés au logger, sinon le message est ignoré Le message Le type Level définit niveaux pour les messages. Les niveaux sont ordonnés : lorsque le Logger est activé pour un niveau tous les niveaux supérieurs le sont également Les niveaux dans l'ordre décroissant Niveau par défaut Niveau OFF SEVERE WARNING INFO CONFIG FINE FINER FINEST ALL Description Aucun niveau Pour indiquer un problème sérieux Pour signaler un problème potentiel Message d'information Configuration Trace d'exécution Trace d'exécution plus précise Trace d'exécution encore plus précise Tous les niveaux La méthode void setlevel(level newlevel) de la classe Logger permet de modifier le niveau pour lequel le journal est activé. Exemple : pour logger tous les messages logger.setlevel(level.all) Philippe GENOUD UJF Novembre

6 Ecriture d'un message pour simplifier l'envoi de message dans le journal il existe pour chaque niveau une méthode qui évite d'avoir à spécifier le niveau en paramètre. public void severe(string msg) public void warning(string msg) public void info(string msg) public void config(string msg) public void fine(string msg) public void finer(string msg) public void finest(string msg) Exemple : logger.info("connection closed"); est équivalent à Logger.log(LEVEL.INFO,"connection closed"); Philippe GENOUD UJF Novembre Formatage des messages A un handler est associé un formateur qui se charge de la mise en forme des messages avant leur écriture dans le journal L'API logging propose deux classes de formatage de base SimpleFormatter XMLFormatter (défaut pour les FileHandler) Associés aux handlers pour formater les LogRecords Il est possible de créer son propre "formateur" en étendant la classe Formatter Formatter Utilisation du message setformatter pour fixer le formateur d'un objet Handler SimpleFormatter XMLFormatter Syntaxe : void setformatter(formatter newformatter) MyFormatter Exemple : fh.setformatter(new myformatter()); Philippe GENOUD UJF Novembre

7 Formatage des messages public static void main(string[] args) throws SecurityException, IOException { Logger logger = Logger.getLogger("monLogger"); Handler fh = new FileHandler("myLog.log"); Fichier mylog.log logger.addhandler(fh); logger.log(level.info, "coucou"); <?xml version="1.0" encoding="windows-1252" standalone="no"?> <!DOCTYPE log SYSTEM "logger.dtd"> <log> <record> <date> t19:32:13</date> <millis> </millis> <sequence>0</sequence> <logger>monjournal</logger> <level>info</level> <class>poo.cours.logging.testapilogging</class> <method>main</method> <thread>10</thread> <message>coucou</message> </record> </log> public static void main(string[] args) throws SecurityException, IOException { Logger logger = Logger.getLogger("monLogger"); Handler fh = new FileHandler("myLog.log"); Utilisation du formateur par défaut : XMLFormatter Handler fh.setformatter(new SimpleFormatter()); logger.addhandler(fh); logger.log(level.info, "coucou"); Utilisation d'un formateur SimpleFormatter Informations extraites de l'objet LogRecord Fichier mylog.log 13 nov :39:35 poo.cours.logging.testapilogging main INFO: coucou Philippe GENOUD UJF Novembre Formatage des messages Définition d'une nouvelle classe de Formatter package poo.cours.logging; import java.util.date; import java.util.logging.formatter; import java.util.logging.handler; import java.util.logging.logrecord; public class MonFormateur extends Formatter public String format(logrecord record) { return "le message '" + record.getmessage() + "' est arrivé à " + new Date(record.getMillis()) + public String gethead(handler h) { return "debut du public String gettail(handler h) { return "\nfin du log\n"; Écriture d'un entête et d'une fin au journal Formatage d'un enregistrement public static void main(string[] args) throws SecurityException, IOException { Logger logger = Logger.getLogger("monLogger"); Handler fh = new FileHandler("myLog.log"); Handler fh.setformatter(new MonFormateur()); logger.addhandler(fh); logger.log(level.info, "coucou"); Utilisation d'un formateur MonFormateur Fichier mylog.log debut du log le message 'coucou' est arrivé à Thu Nov 13 22:52:12 CET 2008 fin du log Philippe GENOUD UJF Novembre

8 Filtrage Les filtres permettent à l'application de définir éventuelleent ses propres règles de filtrage des LogRecords en plus des niveaux de message Un filtre peut être associé àlogger ou à un Handler Méthode void setfilter(filter newfilter) des classes Logger et Handler Un filtre est définit en implémentant l'interface Filter. public boolean isloggable(logrecord record) Exemple : import java.util.logging.filter; import java.util.logging.logrecord; public class myfilter implements Filter { // décide si l enregistrement doit être publié ou pas public boolean isloggable(logrecord record) { return record.getmessage().startswith("debug");; Philippe GENOUD UJF Novembre Hiérarchie des Loggers public static void main(string[] args) throws SecurityException, IOException { Logger logger = Logger.getLogger("monLogger"); Handler fh = new FileHandler("myLog.log"); Handler fh.setformatter(new MonFormateur()); logger.addhandler(fh); logger.log(level.info, "coucou"); Utilisation d'un formateur MonFormateur Fichier mylog.log debut du log le message 'coucou' est arrivé à Thu Nov 13 22:52:12 CET 2008 fin du log Sur la console : P:\CoursAPILogging\bin>java poo.cours.logging.testapilogging 14 nov :01:41 poo.cours.logging.testapilogging main INFO: coucou P:\CoursAPILogging\bin> D'où provient cette sortie? Le logger spécifié dans le programme n'a qu'un handler de type FileHandler Philippe GENOUD UJF Novembre

9 Explication : Hiérarchie des Loggers Les Loggers sont organisés en une structure arborescente Logger racine toujours défini sans nom ConsoleHandler par défaut Chaque Logger a un Logger parent Par défaut un Logger transmet les LogRecords à ses Handlers mais aussi à son Logger parent qui les transmet à ses propres Handlers (de manière récursive jusqu'au Logger racine) "" root Logger ConsoleHandler Console 14 nov :01:41 poo.cours.logging.testapilogging main INFO: coucou "monlogger" Le Logger parent ne fait pas de filtrage ou de contrôle de niveau du LogRecord logger.log(level.info, "coucou"); FileHandler Fichier mylog.log debut du log le message 'coucou' est arrivé à Thu Nov 13 22:52:12 CET 2008 fin du log Philippe GENOUD UJF Novembre Hiérarchie des Loggers La hiérarchie des loggers est construite à partir de leurs noms Dans un nom de logger un '.' correspond à un niveau de hiérarchie Niveau 0 "" Logger racine Logger l1 = Logger.getLogger("l1"); Logger l1_1 = Logger.getLogger("l1.1"); Logger l1_2 = Logger.getLogger("l1.2"); Niveau 1 Niveau 2 l1 l1.1 l1.2 Logger l1_1_1 = Logger.getLogger("l1.1.1"); Niveau 3 l1.1.1 Un Logger hérite un certain nombre d'attributs de ses parents LogingLevel : si est null, le Logger hérite du premier LoggingLevel non null parmi ses parents Handlers : par défaut le Logger transmet récursivement à tous parents les LogRecord qu'il génère ResourceBundle : pour la localisation (comme pour le LogingLevel, si le ResourceBundle est null, il est alors hérité au travers de la hiérarchie des loggers) C'est joli, mais à quoi cela sert tout cela? Philippe GENOUD UJF Novembre

10 Hiérarchie des Loggers MyClass1 La hiérarchie des Loggers et le forwarding des LogRecords permet d'avoir un contrôle fin sur la journalisation. En utilisant des noms de logger qui correspondent à la hiérarchie des packages on peut facilement contrôler le logging package par package (voire classe par classe) ce qui peut être très utile pour une analyse fine d'une application package package1.subpackage1;... public class MyClass1 { private static Logger logger = Logger.getLogger("package1.subPackage1.MyClass1"); package par défaut package1 subpackage1 subpackage2 MyClassN ""... package2 Recommandation de la documentation de l'api logging - Nom complet (fully qualified name) de la classe (une journal par classe) - Nom du package (toutes les classes du package utilisent le même journal) LogManager.getLogManager(). getlogger("package1.subpackage1").setlevel(level.all) Fixe un niveau de journal ALL pour toutes les classes du package package1.subpackage1 Philippe GENOUD UJF Novembre Configuration des journaux La configuration par défaut du LogManager est initialisée à partir d'un fichier de propriétés logging.properties défini dans le répertoire lib du JRE de la JVM Cette configuration par défaut peut être changée en modifiant ce fichier Possibilité d'utiliser une autre fichier de configuration à l'exécution java -Djava.util.logging.config.file=myLoggingconfigurationFile # Global properties handlers= java.util.logging.consolehandler, java.util.logging.filehandler.level= INFO # # Handler specific properties. # #default file output is in user's home directory. java.util.logging.filehandler.pattern = %h/java%u.log java.util.logging.filehandler.limit = java.util.logging.filehandler.count = 1 java.util.logging.filehandler.formatter = java.util.logging.xmlformatter # Limit the message that are printed on the console to INFO and above. java.util.logging.consolehandler.level = INFO java.util.logging.consolehandler.formatter = java.util.logging.simpleformatter # extra control for each logger. # set the com.xyz.foo logger to only log SEVERE messages. com.xyz.foo.level = SEVERE Philippe GENOUD UJF Novembre

11 Conclusion Java.util.logging fourni une API standard pour la journalisation Simple, flexible, efficace Il existe d'autres alternatives qui offrent plus de fonctionnalités: Log4j du projet Apache Extrait de la FAQ : Why should I use log4j when JDK 1.4 already ships with a logging API? Although both APIs are conceptually similar, the log4j API is significantly more flexible and offers many more features, too numerous to be listed here. Commons Logging du projet Jakarta Commons jlo Monolog développée par le consortium ObjectWeb Philippe GENOUD UJF Novembre Références An Introduction to the Java Logging API, Brian R. Gilstrap Java Logging Technology Philippe GENOUD UJF Novembre