Utilisation d'un programme de consignation

Vous pouvez utiliser la consignation Java™ pour consigner des messages et ajouter une fonction de trace.

Pourquoi et quand exécuter cette tâche

Java fournit un package de consignation et de trace, java.util.logging, pour vous permettre d'instrumenter vos applications. La présente rubrique fournit des recommandations sur l'utilisation du module de journal et de trace.

Procédure

  1. Utilisez le niveau WsLevel.DETAIL et les niveaux supérieurs pour les messages, et les niveaux inférieurs pour la fonction de trace. L'API d'extension WebSphere Application Server (package com.ibm.websphere.logging) contient la classe WsLevel.
    Pour les messages, utilisez :
    WsLevel.FATAL 
    Level.SEVERE 
    Level.WARNING 
    WsLevel.AUDIT 
    Level.INFO 
    Level.CONFIG 
    WsLevel.DETAIL
    Pour la trace, utilisez :
    Level.FINE 
    Level.FINER 
    Level.FINEST
  2. Utilisez la méthode log de consignation au lieu de la méthode logrb. La méthode logp accepte les paramètres de nom de classe et de méthode. Les méthodes log et logrb essaient généralement de déduire ces informations, mais la pénalité de performance est prohibitive. En général, la méthode logp a moins d'impact sur les performances que la méthode log ou logrb.
  3. Evitez d'utiliser la méthode logrb. Cette méthode entraîne une mise en mémoire cache insuffisante pour les regroupements de ressources et des performances médiocres.
  4. Utilisez la méthode isLoggable afin d'éviter de créer des données pour un appel de consignation qui ne sera pas consigné. Exemple :
    if (logger.isLoggable(Level.FINEST)) {
     	String s = dumpComponentState();	// some expensive to compute method
     	logger.logp(Level.FINEST, className, methodName, "componentX state 
    dump:\n{0}", s);
     }

Messages localisés

L'exemple suivant s'applique aux messages localisés :
// note - generally avoid use of FINE, FINER, FINEST levels for messages to be consistent with
// WebSphere Application Server

String componentName = "com.ibm.websphere.componentX";
String resourceBundleName = "com.ibm.websphere.componentX.Messages";
Logger logger = Logger.getLogger(componentName, resourceBundleName);

// "Convenience" methods - not generally recommended due to lack of class 
/ method names
//   - cannot specify message substitution parameters
//   - cannot  specify class and method names
if (logger.isLoggable(Level.SEVERE))
	logger.severe("MSG_KEY_01");

if (logger.isLoggable(Level.WARNING))
	logger.warning("MSG_KEY_01");

if (logger.isLoggable(Level.INFO))
	logger.info("MSG_KEY_01");

if (logger.isLoggable(Level.CONFIG))
	logger.config("MSG_KEY_01");


// log methods are not generally used due to lack of class and method 
names
//   - enable use of WebSphere Application Server-specific levels
//   - enable use of message substitution parameters
//   - cannot specify class and method names
if (logger.isLoggable(WsLevel.FATAL))
	logger.log(WsLevel.FATAL, "MSG_KEY_01", "parameter 1");

if (logger.isLoggable(Level.SEVERE))
	logger.log(Level.SEVERE, "MSG_KEY_01", "parameter 1");

if (logger.isLoggable(Level.WARNING))
	logger.log(Level.WARNING, "MSG_KEY_01", "parameter 1");

if (logger.isLoggable(WsLevel.AUDIT))
	logger.log(WsLevel.AUDIT, "MSG_KEY_01", "parameter 1");

if (logger.isLoggable(Level.INFO))
	logger.log(Level.INFO, "MSG_KEY_01", "parameter 1");

if (logger.isLoggable(Level.CONFIG))
	logger.log(Level.CONFIG, "MSG_KEY_01", "parameter 1");

if (logger.isLoggable(WsLevel.DETAIL))
	logger.log(WsLevel.DETAIL, "MSG_KEY_01", "parameter 1");


// logp methods are the way to log
//   - enable use of WebSphere Application Server-specific levels
//   - enable use of message substitution parameters
//   - enable use of class and method names
if (logger.isLoggable(WsLevel.FATAL))
	logger.logp(WsLevel.FATAL, className, methodName, "MSG_KEY_01", 
"parameter 1");

if (logger.isLoggable(Level.SEVERE))
	logger.logp(Level.SEVERE, className, methodName, "MSG_KEY_01", 
"parameter 1");

if (logger.isLoggable(Level.WARNING))
	logger.logp(Level.WARNING, className, methodName, "MSG_KEY_01", 
"parameter 1");

if (logger.isLoggable(WsLevel.AUDIT))
	logger.logp(WsLevel.AUDIT, className, methodName, "MSG_KEY_01", 
"parameter 1");

if (logger.isLoggable(Level.INFO))
	logger.logp(Level.INFO, className, methodName, "MSG_KEY_01", 
"parameter 1");

if (logger.isLoggable(Level.CONFIG))
	logger.logp(Level.CONFIG, className, methodName, "MSG_KEY_01", 
"parameter 1");

if (logger.isLoggable(WsLevel.DETAIL))
	logger.logp(WsLevel.DETAIL, className, methodName, "MSG_KEY_01", 
"parameter 1");


// logrb methods are not generally used due to diminished performance 
of switching resource bundles dynamically
//   - enable use of WebSphere Application Server-specific levels
//   - enable use of message substitution parameters
//   - enable use of class and method names
String resourceBundleNameSpecial = 
"com.ibm.websphere.componentX.MessagesSpecial";

if (logger.isLoggable(WsLevel.FATAL))
	logger.logrb(WsLevel.FATAL, className, methodName, resourceBundleNameSpecial, 
"MSG_KEY_01", "parameter 1");

if (logger.isLoggable(Level.SEVERE))
	logger.logrb(Level.SEVERE, className, methodName, resourceBundleNameSpecial, 
"MSG_KEY_01", "parameter 1");

if (logger.isLoggable(Level.WARNING))
	logger.logrb(Level.WARNING, className, methodName, resourceBundleNameSpecial, 
"MSG_KEY_01", "parameter 1");

if (logger.isLoggable(WsLevel.AUDIT))
	logger.logrb(WsLevel.AUDIT, className, methodName, resourceBundleNameSpecial, 
"MSG_KEY_01", "parameter 1");

if (logger.isLoggable(Level.INFO))
	logger.logrb(Level.INFO, className, methodName, resourceBundleNameSpecial, 
"MSG_KEY_01", "parameter 1");

if (logger.isLoggable(Level.CONFIG))
	logger.logrb(Level.CONFIG, className, methodName, resourceBundleNameSpecial, 
"MSG_KEY_01", "parameter 1");

if (logger.isLoggable(WsLevel.DETAIL))
	logger.logrb(WsLevel.DETAIL, className, methodName, resourceBundleNameSpecial, 
"MSG_KEY_01", "parameter 1");
Pour la fonction de trace ou le contenu non localisé, l'exemple applicable est le suivant :
// note - generally avoid use of FATAL, SEVERE, WARNING, AUDIT,
// INFO, CONFIG, DETAIL levels for trace 
// to be consistent with WebSphere Application Server

String componentName = "com.ibm.websphere.componentX";
Logger logger = Logger.getLogger(componentName);

// Entering / Exiting methods are used for non trivial methods
if (logger.isLoggable(Level.FINER))
	logger.entering(className, methodName);
	
if (logger.isLoggable(Level.FINER))
	logger.entering(className, methodName, "method param1");

if (logger.isLoggable(Level.FINER))
	logger.exiting(className, methodName);

if (logger.isLoggable(Level.FINER))
	logger.exiting(className, methodName, "method result");


// Throwing method is not generally used due to lack of message - use 
logp with a throwable parameter instead
if (logger.isLoggable(Level.FINER))
	logger.throwing(className, methodName, throwable);


// Convenience methods are not generally used due to lack of class 
/ method names
//   - cannot specify message substitution parameters
//   - cannot specify class and method names
if (logger.isLoggable(Level.FINE))
	logger.fine("This is my trace");

if (logger.isLoggable(Level.FINER))
	logger.finer("This is my trace");

if (logger.isLoggable(Level.FINEST))
	logger.finest("This is my trace");


// log methods are not generally used due to lack of class and 
method names
//   - enable use of WebSphere Application Server-specific levels
//   - enable use of message substitution parameters
//   - cannot specify class and method names
if (logger.isLoggable(Level.FINE))
	logger.log(Level.FINE, "This is my trace", "parameter 1");

if (logger.isLoggable(Level.FINER))
	logger.log(Level.FINER, "This is my trace", "parameter 1");

if (logger.isLoggable(Level.FINEST))
	logger.log(Level.FINEST, "This is my trace", "parameter 1");


// logp methods are the recommended way to log
//   - enable use of WebSphere Application Server-specific levels
//   - enable use of message substitution parameters
//   - enable use of class and method names
if (logger.isLoggable(Level.FINE))
	logger.logp(Level.FINE, className, methodName, "This is my trace", 
"parameter 1");

if (logger.isLoggable(Level.FINER))
	logger.logp(Level.FINER, className, methodName, "This is my trace", 
"parameter 1");

if (logger.isLoggable(Level.FINEST))
	logger.logp(Level.FINEST, className, methodName, "This is my trace", 
"parameter 1");


// logrb methods are not applicable for trace logging because no localization 
is involved
Il existe des situations dans lesquelles vous souhaitez propager les enregistrements de journaux vers vos propres gestionnaires de journaux, plutôt que de participer à la consignation intégrée. Pour utiliser un gestionnaire de journaux autonome, affectez à l'option useParentHandlers la valeur false dans votre application. Le mécanisme de création d'un gestionnaire personnalisé constitue le support de classe de gestionnaire fourni par IBM® Developer Kit, Java Technology Edition. Si vous ne maîtrisez pas bien les gestionnaires tels qu'ils sont implémentés par le kit du développeur, vous pouvez obtenir plus d'informations provenant de divers textes ou en lisant la documentation API pour l'API java.util.logging. Vous trouverez ci-dessous un exemple de gestionnaire personnalisé :
import java.io.FileOutputStream;
import java.io.PrintWriter;
import java.util.logging.Handler;
import java.util.logging.LogRecord;

/**
 * MyCustomHandler outputs contents to a specified file
 */
public class MyCustomHandler extends Handler {

	FileOutputStream fileOutputStream;
	PrintWriter printWriter;

	public MyCustomHandler(String filename) {
		super();

		// check input parameter
		if (filename == null || filename == "")
			filename = "mylogfile.txt";
		
		try {
			// initialize the file 
			fileOutputStream = new FileOutputStream(filename);
			printWriter = new PrintWriter(fileOutputStream);
			 setFormatter(new SimpleFormatter());
		}
		catch (Exception e) {
			// implement exception handling...
		}
	}

	/* (non-API documentation)
	 * @see java.util.logging.Handler#publish(java.util.logging.LogRecord)
	 */
	public void publish(LogRecord record) {
		// ensure that this log record should be logged by this Handler
		if (!isLoggable(record))
			return;
		
		// Output the formatted data to the file
		printWriter.println(getFormatter().format(record));
	}

	/* (non-API documentation)
	 * @see java.util.logging.Handler#flush()
	 */
	public void flush() {
		printWriter.flush();
	}

	/* (non-API documentation)
	 * @see java.util.logging.Handler#close()
	 */
	public void close() throws SecurityException {
		printWriter.close();
	}
}

Un filtre personnalisé constitue un contrôle secondaire facultatif des éléments consignés, qui s'ajoute au contrôle déjà effectué par le niveau. Le mécanisme de création d'un filtre personnalisé constitue le support d'interface de filtre fourni par IBM Developer Kit, Java Technology Edition. Si vous ne maîtrisez pas bien les filtres tels qu'ils sont implémentés par le kit du développeur, vous pouvez obtenir plus d'informations provenant de divers textes ou en lisant la documentation API pour l'API java.util.logging.

L'exemple suivant présente un filtre personnalisé :

/**
 * This class filters out all log messages starting with SECJ022E, SECJ0373E, or SECJ0350E.
 */
import java.util.logging.Filter;
import java.util.logging.Handler;
import java.util.logging.Logger;
import java.util.logging.LogRecord;

public class MyFilter implements Filter {
	public boolean isLoggable(LogRecord lr) {
		String msg = lr.getMessage();
		if (msg.startsWith("SECJ0222E") || msg.startsWith("SECJ0373E") || msg.startsWith("SECJ0350E")) {
			return false;
		}
		return true;
	}
}

//This code will register the log filter with the root Logger's handlers
// (including the WAS system logs):
...
Logger rootLogger = Logger.getLogger("");
rootLogger.setFilter(new MyFilter());

Un formateur met en forme des événements. Des manipulateurs sont associés à un ou plusieurs formateurs. Le mécanisme de création d'un formateur personnalisé constitue le support de classe de formateur fourni par IBM Developer Kit, Java Technology Edition. Si vous ne maîtrisez pas bien les formateurs tels qu'ils sont implémentés par le kit du développeur, vous pouvez obtenir plus d'informations provenant de divers textes ou en lisant la documentation API pour l'API java.util.logging.

L'exemple suivant présente un formateur personnalisé :

import java.util.Date;
import java.util.logging.Formatter;
import java.util.logging.LogRecord;

/**
 * MyCustomFormatter formats the LogRecord as follows:
 * date   level   localized message with parameters 
 */
public class MyCustomFormatter extends Formatter {

	public MyCustomFormatter() {
		super();
	}

	public String format(LogRecord record) {
		
		// Create a StringBuffer to contain the formatted record
		// start with the date.
		StringBuffer sb = new StringBuffer();
		
		// Get the date from the LogRecord and add it to the buffer
		Date date = new Date(record.getMillis());
		sb.append(date.toString());
		sb.append(" ");
		
		// Get the level name and add it to the buffer
		sb.append(record.getLevel().getName());
		sb.append(" ");
		 
		// Get the formatted message (includes localization 
		// and substitution of paramters) and add it to the buffer
		sb.append(formatMessage(record));
		sb.append("\n");

		return sb.toString();
	}
}

L'ajout de formateurs, de filtres et de gestionnaires personnalisés permet de personnaliser l'environnement de consignation en plus de la configuration de l'infrastructure de consignation par défaut de WebSphere Application Server. L'exemple suivant indique comment ajouter un gestionnaire pour le traitement des requêtes à la sous-arborescence com.myCompany des programmes de consignation (voir la rubrique Configuration de la hiérarchie du programme de consignation). La méthode principale de cet exemple indique comment utiliser le programme de consignation nouvellement configuré.

import java.util.Vector;
import java.util.logging.Filter;
import java.util.logging.Formatter;
import java.util.logging.Handler;
import java.util.logging.Level;
import java.util.logging.Logger;

public class MyCustomLogging {

	public MyCustomLogging() {
		super();
	}

	public static void initializeLogging() {
		
		// Get the logger that you want to attach a custom Handler to
		String defaultResourceBundleName = "com.myCompany.Messages";
		Logger logger = Logger.getLogger("com.myCompany", defaultResourceBundleName);
		
		// Set up a custom Handler (see MyCustomHandler example)
		Handler handler = new MyCustomHandler("MyOutputFile.log");
		
		// Set up a custom Filter (see MyCustomFilter example)
		Vector acceptableLevels = new Vector();
		acceptableLevels.add(Level.INFO);
		acceptableLevels.add(Level.SEVERE);
		Filter filter = new MyCustomFilter(acceptableLevels);
		
		// Set up a custom Formatter (see MyCustomFormatter example)
		Formatter formatter = new MyCustomFormatter();

		// Connect the filter and formatter to the handler
		handler.setFilter(filter);
		handler.setFormatter(formatter);
		
		// Connect the handler to the logger
		logger.addHandler(handler);
		
		// avoid sending events logged to com.myCompany showing up in WebSphere
		// Application Server logs
		logger.setUseParentHandlers(false);
				
	}

	public static void main(String[] args) {
		initializeLogging();
		
		Logger logger = Logger.getLogger("com.myCompany");
		
		logger.info("This is a test INFO message");
		logger.warning("This is a test WARNING message");
		logger.logp(Level.SEVERE, "MyCustomLogging", "main", "This is a test SEVERE message");
	}
}
Lorsque le programme ci-dessus est exécuté, la sortie du programme est inscrite dans le fichier MyOutputFile.log. Le contenu du journal se trouve dans le fichier journal attendu, tel que contrôlé par le gestionnaire personnalisé, et est formaté suivant la définition du formateur personnalisé. Le message d'avertissement a été filtré comme il a été spécifié par la configuration du filtre personnalisé. La sortie est la suivante :
C:\>type MyOutputFile.log
Sat Sep 04 11:21:19 EDT 2004 INFO This is a test INFO message
Sat Sep 04 11:21:19 EDT 2004 SEVERE This is a test SEVERE message

Icône indiquant le type de rubrique Rubrique de tâche



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=ttrb_createloginstance
Nom du fichier : ttrb_createloginstance.html