Groupe 1C (normes)
Date de création :	16 mai 2003
Dernière modification :	15 Octobre 2004
Diffusion :	internet

Gestion des logs dans UPortal

Présentation de log4j

log4j est un outil de log open-tool développé par Apache. C'est un jeu d'API qui permet aux développeurs de générer des logs depuis leur code et de configurer ensuite le niveau, la sortie et le formattage des logs à l'aide de fichiers de configuration externes à l'application

C'est l'outil qui est utilisé par uPortal pour générer des logs. Il n'est donc pas nécessaire de l'installer, il est déjà présent.
Par défaut log4j définit 5 niveaux de priorité :
- le niveau debug pour les messages de debuggage
- le niveau info pour les messages des applications en mode verbose (verbeuses)
- le niveau warn pour les messages d'erreurs potentielles (les warnings comme on dit)
- le niveau error pour les messages d'erreurs graves mais non bloquants
- le niveau fatal pour les messages d'erreurs provoquant l'arrêt de l'application
Il est cependant possible de rajouter ses propres niveaux
log4j met par ailleurs en oeuvre 3 grandes classes : le Logger qui envoie les logs à un Appender qui les affiche selon un Layout.
la classe Logger est responsable de la majorité des opérations de log. A un logger sera associé un niveau minimum de log et il n'enverra à l'Appender que les logs qui correspondent à ce niveau ou à un niveau supérieur. Il y a au moins un logger par application (le RootLogger de niveau Debug par défaut) mais il peut aussi y en avoir plusieurs selon un principe père-fils.
la classe Appender est responsable de diriger les logs vers un flux de sortie. Il existe donc des appenders spécialisés pour les fichiers (FileAppender), la console (ConsoleAppender), les bases de données (JDBCAppender)...
la classe Layout est chargée de mettre en forme l'affichage des logs

Changement de méthode de LOG

L'utilisation du LogService va être abandonné dans les prochaines versions de uPortal. Dans la version 2.4 ce service est déjà deprecated :

 * @deprecated As of uPortal 2.4, please use Apache Commons Logging directly

Il nous est donc indispensable de passer à l'utilisation de Apache Commons Logging.
Ce changement va modifier le code des canaux ainsi que les possibilités offertes.
Nouvelles fonctionnalités :

Possibilité de logger une classe ou un package dans un fichier indépendant ;
Possibilité de logger une classe ou un package dans un niveau différent du portail ;
Possibilité de savoir si la classe ou le package est en niveau de log debug (ou autre).

Utilisation dans UPortal

Cette exemple d'utilisation se base sur un cannal dont le nom de package est : org.esupportail.portal.channels.CLogTest et le nom du canal (de la classe) CLogTest

L'utilisation dans le portail nécessite maintenant :

Deux imports

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

Une variable de classe static

 protected static final Log log = LogFactory.getLog(CLogTest.class);

La variable de classe static va contenir un objet Log. Toutes les méthodes de log utilisées dans le canal vont se baser sur cet objet.

Méthodes intéressantes de Log :

Méthode	Signification
isDebugEnabled	Renvoie un boolean permettant de savoir si on est en niveau de log DEBUG.
info	Action de log en niveau INFORMATION
warn	Action de log en niveau WARNING
error	Action de log en niveau ERROR
debug	Action de log en niveau DEBUG
fatal	Action de log en niveau FATAL

INTERET du isDebugEnabled

Il est noté l'existance de la méthode isDebugEnabled celle ci permet de savoir si la classe est en mode DEBUG.

Il est impératif de l'utiliser avant tout affichage de log DEBUG. Ceci permet de ne pas calculer les chaines de caractères (ou appel de fonction) a écrire dans les logs si ce n'est pas nécessaire. Cette méthode permet donc d'accroitre les performances de vos canaux.


if (log.isDebugEnabled()){
	log.debug("CLogTest:: Constructeur"+obj.tostring()+" - "+xml.dump());
}

Exemple complet :

package org.esupportail.portal.channels.CLogTest;


import org.jasig.portal.PortalException;
import org.jasig.portal.channels.BaseChannel;
import org.jasig.portal.utils.XSLT;
import org.xml.sax.ContentHandler;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class CLogTest extends BaseChannel {
	protected static final Log log = LogFactory.getLog(CLogTest.class);
 
	public CLogTest() { 
        if (log.isDebugEnabled()){
        	log.debug("CLogTest:: Constructeur");
        }
    }

	public void renderXML(ContentHandler out) throws PortalException {
        log.info("CLogTest:: renderXML");
        
        StringBuffer xml = new StringBuffer();
        String stylesheet = "normal"; 
        
        xml.append("<?xml version=\"1.0\" encoding=\"utf-8\"?>"); 
        xml.append("<name>test de log</name>");
        
        XSLT xslt = new XSLT(this);
        xslt.setXML(xml.toString());
      
		if (log.isDebugEnabled()){
        	log.debug("CLogTest:: xml de sortie :"+xml.toString());
        }

        xslt.setXSL("CLogTest.ssl", stylesheet, runtimeData.getBrowserInfo());
        xslt.setStylesheetParameter("baseActionURL",runtimeData.getBaseActionURL());        
        xslt.setTarget(out);
        xslt.transform();
    }
}

Paramétrage pour UPortal

La configuration de log4j se trouve dans le fichier uPortal_rel-X-X-X/properties/logger.properties

la première ligne du fichier log4j.rootCategory=INFO, R indique le logger racine est au niveau INFO. Tous les loggers fils hériteront de lui et auront le niveau INFO par défaut. Par ailleurs, on fera référence à ce logger par l'abbréviation R.
log4j.appender.R=org.apache.log4j.RollingFileAppender nous indique que l'Appender utilisé sera un RollingFileAppender soit un roulement sur des fichiers (équivalent aux logs Oracle pour ceux qui pratiquent).
Ensuite, il s'aggit de donner des paramètres spécifiques à l'Appender :
- log4j.appender.R.File nom du fichier de log
- log4j.appender.R.MaxFileSize taille maxi d'un fichier avant de passer au prochain dans le roulement
- log4j.appender.R.MaxBackupIndex nombre maxi de fichiers sur lequels s'effectue un roulement
log4j.appender.R.layout=org.apache.log4j.PatternLayout précise le type de pattern pour l'Appender de R, soit un PatternLayout qui nous permet de préciser le format des logs selon un motif

Nouvelles possibilités de paramétrage

Avec la nouvelle méthode de log il est possible de changer le paramétrage du log.

Vous pouvez utiliser la configuration de base du portail, ce qui permet d'avoir tous les logs (selon le niveau) dans un fichier, ou vous pouvez découper les logs en plusieurs fichiers avec des niveaux différents.

Dans le code source précédent, nous avons fait appel à la méthode LogFactory.getLog(CLogTest.class). Cette méthode permet d'obtenir un Logger spécifique pour la classe org.esupportail.portal.channels.CLogTest.CLogTest.

Si ce Logger n'est pas définit dans le fichier logger.properties tous les appels de log de cette classe iront dans le fichier global de log.
Au contraire, on peut spécifier un Logger différent pour cette classe :

log4j.category.org.esupportail.portal.channels.CLogTest.CLogTest= DEBUG, test
log4j.additivity.org.esupportail.portal.channels.CLogTest.CLogTest = false

log4j.appender.test = org.apache.log4j.RollingFileAppender
log4j.appender.test.File = test.log
log4j.appender.test.Encoding=UTF-8
log4j.appender.test.MaxFileSize=3000KB
log4j.appender.test.MaxBackupIndex=10
log4j.appender.test.layout=org.apache.log4j.PatternLayout
log4j.appender.test.layout.ConversionPattern=%5p [%t] %c{2}.[%x] %d{MMM/dd HH:mm:ss}    - %m%n

Dans ce cas les logs de la classe org.esupportail.portal.channels.CLogTest.CLogTest iront dans un fichier test.log et non plus le fichier global du portail.

Dans le cas où vous voulez debugger un package (et non une classe unique), il vous suffit de mettre le nom d'un package lors de l'a configuration du Logger :

log4j.category.org.esupportail.portal.channels = DEBUG,test
log4j.additivity.org.esupportail.portal.channels = false
....

Pour mémoire : anciennne utilisation dans UPortal

Les fonctionnalités de log4j sont accessible au travers d'une classe facade de UPortal nommée LogService

Cette classe fait partie des services externes d'UPortal : elle est présente dans le fichier services.xml et est chargée au démarrage de l'application pour ensuite être accessible depuis n'importe où.
Elle implémente le pattern Singleton ce qui indique qu'il n'existe qu'une et une seule instance de cette classe dans notre application.
Pour générer des logs depuis votre channel, il faut donc commencer par importer le service adéquat :

import org.jasig.portal.services.LogService;

Ensuite il faut appeler la méthode log, soit de manière simple avec le niveau de log par INFO défaut :

LogService.instance().log("mon_texte_de_log");

LogService.log("mon_texte_de_log");

Si on veut préciser soit-même le niveau de log, procéder comme suit :

LogService.instance().log(niveau_de_log, "mon_texte_de_log");

LogService.log(niveau_de_log, "mon_texte_de_log");

On a accès aux niveaux suivants :
- LogService.DEBUG
- LogService.ERROR
- LogService.INFO
- LogService.NONE
- LogService.SEVERE
- LogService.WARN

Création : 16 mai 2003 - Olivier Ziller (Université Nancy 2)
Modifications : 08 Octobre 2004 - Julien Marchal (Université Nancy 2) - utilisation apache.commons.logging 15Octobre 2004 - Julien Marchal (Université Nancy 2) - Insister sur le isDebugenable