JMRI: Debugging
Keywords: JMRI panelpro decoderpro help debug debugging log logging

# JMRI: Debugging and System Logging

- Where JMRI Logs to
- Debugging Tools
- Logger Levels and Names
- Logging Configuration
- Debugging XML Files

For installation issues, see Debugging an installation

### Where JMRI Logs to

The System Console can be viewed via Help ⇒ System Console
This displays the log from the current JMRI session.

The "session.log" file contains the log for the current session.
This log file is reset just before each JMRI session startup.
This file can be viewed live with the tail command.

Rolling Log Files contain logging for the current and previous sessions.
These start from "messages.log" and have a maximum file size of 1000KB .
Logs are rolled over, up to 3 files deep.

The session and rolling log files are stored in the "log" directory within the User Settings Directory.
Help ⇒ File Locations ⇒ Open Log Files Location

These defaults can be changed by editing your Logging Configuration.

### Debugging Tools

JMRI System Console
Displays current session log.
Help ⇒ System Console

View / Edit Log Categories
View current logging levels for each Logger category name.
Debug ⇒ Display / Edit Logging Categories

Log Message...
Manually add a LogEvent to the logging.
Debug ⇒ Log Message...

There are various tools for checking files in the Debug Menu.

### Logger Levels and Names

A Logger Category is essentially the name given to an Event Logger.
The Logger Category name is normally defined by the JMRI Java Class associated with it.
Typical Logger Category names would be `jmri.jmrit` or `jmri.jmrit.operations`
Loggers inherit, so for example `apps.jmrit.log.Log4JTreePane` , the Level would be inherited from one of these Logger categories :

- apps.jmrit.log.Log4JTreePane
- apps.jmrit.log
- apps.jmrit
- apps
- Root Logging Level

Setting the Logging Level will also invoke the higher levels.
e.g. setting a Category to WARN will also display ERROR messages but not INFO or below.
The Logging levels are :

- ALL ( TRACE + DEBUG + INFO + WARN + ERROR )
- TRACE ( + DEBUG + INFO + WARN + ERROR )
- DEBUG ( + INFO + WARN + ERROR )
- INFO ( + WARN + ERROR )
- WARN ( + ERROR )
- ERROR
- OFF

The FATAL level ( not in the SLF4J interface hence not used by JMRI ) between ERROR and OFF is omitted for clarity

### Logging Configuration

It is possible to edit the current state of Logger Categories and their Logging Levels via the View / Edit Logging Categories Tool ( Debug Menu ).
Changes are maintained for the duration of the JMRI session.

To make persistent changes to the Logging Configuration effective from JMRI startup, changes will need to be made within the "default_lcf.xml" file.

A "default_lcf.xml" file in the Settings directory will take precedence over the default_lcf.xml file in the main program directory.
The main program directory version will be reset each time JMRI is updated, whereas the user preference version will not be updated.
Some parts of the file are required for JMRI logging setup. The settings version does not inherit from the program directory version.

- Use the existing default_lcf.xml from the program directory as a starting template.
  For a Windows install that's typically "C:\Program Files (x86)\JMRI\default_lcf.xml", or see https://github.com/JMRI/JMRI/blob/master/default_lcf.xml.
- Copy and paste the file from program directory to Settings.
  For a Windows install, that's typically C:/Users/<username>/JMRI/ , or see JMRI Setup: Configuration Files.
- Open up the file using a text editor.
- Add customisations towards the end of the Loggers section, where the examples are ( see below ).
- Save the file.
- JMRI will read the file on each restart.

The "default_lcf.xml" file contains lots of comments on what the various terms mean.
Content within the `<!-- -->` symbols is processed as a comment, not part of the configuration.

Of most relevance is the section towards the bottom of the file containing the Logger elements.
eg. to enable logging at DEBUG level for the whole of JMRI core, remove the comment arrows.

`<Logger name="jmri" level="DEBUG"/>`

The Logger name is the Logging Category ( in this case "jmri" ) which will set jmri and all classes inheriting from it ( a lot of classes ) to log code comments which are set at DEBUG Level or higher.

If the file is saved and JMRI restarted, there will be a LOT of extra events in the logs.

The TRACE and DEBUG levels will output a lot of information, and will slow down operation significantly.

It is possible to request more information on just parts of JMRI.

For example, Layout Editor begugging could be enabled by adding
`<Logger name="jmri.jmrit.display.layoutEditor" level="DEBUG"/>`

Remember to save the default_lcf.xml file in your Settings for the configuration to be retained following JMRI being updated.

Prior to JMRI 5.5.4 , logging configuration was controlled by a "default.lcf" file within the JMRI program install directory, or overridden by a file of the same name in the user settings directory.
Open that file with a standard text editor for details on how to change the logging category levels.

For the full configuration specification and to change other logging settings ( rolling log file sizes etc. ), see Log4J2 xml Configuration.

For more technical details on JMRI Logging, see JMRI Code: How to Use the Logging Facilities.

### Debugging problems with XML files

When an XML file can't be parsed, you'll get some hard-to-understand error messages. The most important part of this is the line number. Use that to start looking for the problem.

You might be able to get better debugging information by trying to open the file with Internet Explorer. The debugging information it provides is generally more detailed than that provided by the XML routines in the JDOM libraries used by JMRI and DecoderPro.

Note that Explorer needs to see both the .xml file, plus the definition information in the .xsd Schema file. If you get a message like "error in system resource", you need to put a copy of the associated .xsd file (e.g. decoder-config.xsd; see the top few lines of your file) in the directory with your new file. Schema .xsd's can be found in the Schema subdirectory of the xml directory.

Also see the checking tools within the Debug Menu.