JMRI: How to Use the Logging Facilities

This page provides a little information on how JMRI logs error, status and debugging information.

For other details on JMRI internals, please see the technical pages.

JMRI uses the Jakarta Log4J package to handle logging during program operation.

Log4J provides several levels of messages:

Error
Warning
Info - summary information during normal operation
Debug - information on the internal operation of the program. There is a lot of this, and turning it all on can slow the program down significantly.

By convention, JMRI applications will attempt to initialize Log4J using a "default.lcf" file. The JMRI distributions contain a version of this file with extensive comments. (This file needs to be in the "Program Directory", which can be found by selecting the "Locations" item in the main help menu)

If you change the line:

 log4j.rootCategory=DEBUG, A1

 log4j.rootCategory=DEBUG, A1, R

log entries will be written to both the "console" by "A1", and a file by "R".

To log messages from a class named MyClass, add this to the bottom of the class file:

	static org.apache.log4j.Category log 
	        = org.apache.log4j.Category.getInstance(MyClass.class.getName());

Then for each message to log insert a line like:


	log.debug("message");

If the message is not just an explicit string, you should use this form instead:

	if (log.isDebugEnabled()) log.debug("Found "+numberEntrie());

so the program doesn't waste time forming the message string (in this case, calling numberEntries() and concatenating the strings) if the log.debug call isn't going to store it anyway.

Logging Levels

Level	Code Fragment	Use
DEBUG	if (log.isDebugEnabled()) log.debug(..)	Detailed messages, only used in debugging
INFO	if (log.isInfoEnabled())log.info(..)	Routine messages you want to see in normal operation
WARN	log.warn(..)	The program is still operating, sort of, but something here needs to be looked at
ERROR	log.error(..)	Indicates the desired operation is not going to happen, and explains why
FATAL	log.fatal(..)	Rarely used, these are the last things the program says before shutting down unexpectedly