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".

The "default.lcf" file determines the destination and format of the logged messages. By default, you get lines that look like:

514668 [AWT-EventQueue-0] WARN jmri.jmrit.powerpanel.PowerPane  - No power manager instance found, panel not active

The columns are:

514668 - time in milliseconds since the program started
[AWT-EventQueue-0] - the thread that emitted the message, useful if you've created your own in a script
WARN - the severity of the message
jmri.jmrit.powerpanel.PowerPane - the place in the code (class name) that emitted the message
No power manager instance found, panel not active - the message itself

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

	private static final org.apache.log4j.Logger log 
	        = org.apache.log4j.Logger.getLogger(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 "+numberEntries());

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