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.

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.isInfoDebug()) 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.