+ The Java Console, Logging and Reporting Bugs
+
+ Like most programs, Jalview contains bugs, despite our best efforts. + However, Jalview also produces a series of messages during its + operation, often referred to as 'logs'. These logs provide a record + of Jalview's operation. They can also be extremely useful when reporting bugs, since they help the + Jalview developers diagnose and find a workaround for specific + problems that you might encounter. +
++ The primary place to look for logs is in the Java + Console which you can open from within Jalview by going to the Tools + menu and checking the box next to Show Java Console. This + option is stored in your Jalview preferences file and so is + remembered across Jalview sessions. +
+The Java Console will show you information about what the + Jalview application is doing (often in the background) whilst it is + running.
+However, when tracking down problems preventing Jalview from + starting up properly, you need to look at the startup logs - which + are not shown in the Jalview Console. The location of these depends + on how you launched Jalview:
+
+ Jalview Desktop Installation Launch Logs
If you are using
+ a standard desktop version of Jalview installed from one of our
+ install4j installers, then messages about Jalview's initial launch
+ can be found in
+
JALVIEW_APP_DIR/launcher.log+ where + JALVIEW_APP_DIR is the directory that Jalview's application + was installed into. +
Jalview Executable Jar Launch Logs
If you are using the Jalview executable jar file (also
+ used by bioconda and OSX homebrew installations) then the default run class (
+ jalview.bin.Launcher -- a minimised launcher that will set
+ memory and linux dpi settings before re-launching
+ jalview.bin.Jalview), will output logging information to
+ STDOUT and STDERR.
+
+ Java Console and Log Level +
++ The Java Console is opened by selecting Tools + → Show Java Console. The visibility of the console is stored + in your preferences, so if you quit Jalview with the console open, + it will be shown the next time you start Jalview. You can close the + console by selecting the same menu option again, or just closing the + console window. +
+The Java Console's text display always shows information about + your system and Jalview installation details. The rest are the most + recent messages output during your Jalview session. Some messages + are only captured by the console when it is open, so to get a full + log for debugging a problem, enable the console and then restart + Jalview.
+ ++ Jalview logging will automatically scroll the text in the Java Console + but if you want to examine a particular part of the logs whilst logging + is still going on you can click on any part of the text area to + stop this behaviour. A border should appear arround the + text area to signify that autoscroll has been turned off. You can + toggle the autoscroll behaviour on and off by clicking again on the + text area. +
++ You can temporarily control the detail of what appears as output by + selecting a Log level using the drop-down list at the + bottom left of the console. There are several levels to choose from: + The most verbose is TRACE, followed by DEBUG, INFO, WARN. When the + Console is opened, the default level will be chosen (INFO). +
++ Note! If you change the log level in the Java + Console, this change will only persist for as long as the console + is open. Once you close the console the log level will revert back + to what it had been when you opened the console (usually INFO). +
+Permanently changing Jalview's default log level
+ You can change the default log level by editing the Jalview
+ preferences file, .jalview_properties, found in your home
+ directory (on Windows: %HOMEPATH%, or the folder above 'My
+ Documents'; on macOS: ~ or /Users/username; on linux/unix:
+ ~ or /home/username), and setting the property logs.Jalview.level
+ to the log level you prefer, e.g.
+
+ logs.Jalview.level=DEBUG ++ You can also set the property +
+ logs.Axis.level=DEBUG ++
to get debug information for Jalview's JPred service. The Axis log + level cannot be set from within the Java Console. +
++ You can also set the logs.jalview.level property to a log level + not usually presented in the Java Console (though restricted to log + levels used by Apache Log4j -- see Log4j + Custom Log Levels for details of the standard log levels + available). Jalview does not currently define any custom log levels. + If you do set the property with a log level that is normally not + visible in the Java Console this should be respected and visibly + selected when you open the console. +
++ The Clear button at the bottom of the console will clear + all logging messages except for the initial system information which + is rewritten to the console. +
++ The Copy to clipboard button at the bottom right of the + console will copy all of the text in the console to your system + clipboard, ready to paste into another application (e.g. email + composer or issue tracker). +
+ + + ++ If you come across a problem in Jalview where something is not + working as described, or how you think it should, you should first + check the Jalview FAQ to + see if this is a known problem and if there is a suggested + workaround. +
++ If there is no FAQ answer covering your problem then you can submit + a bug report on the Jalview + Issue Tracker. It is good practice to search the issue tracker + first to see if the issue has already been reported. If an issue + already exists please continue to add your own comments to the issue + which may well help narrow down the problem, if not then you can + create an account and submit a new bug report: +
+
+ Make sure that you set Project to Jalview (JAL), and Issue
+ Type to Bug or New Feature or Improvement
+ appropriately.
Give a one line summary of the issue in the Summary.
+
In the Environment text box you can describe the
+ system you are using. This is usually most easily done by opening
+ the Java Console, clicking the Clear button, and then
+ immediately on the Copy to clipboard button, and then
+ pasting the clipboard into the text box.
+
+ You can then give more detailed information about how to recreate + the problem in the Description text box. If you want to + attach any screenshots or example alignment files that demonstrate + the problem then you can drag them to the Create Issue dialog in + your browser, or use the Attachment browse facility to + locate them on your computer. +
+ +
+ To help the Jalview team with diagnosing a particular issue, it is
+ really helpful if you can also add more detailed logs output whilst
+ re-creating the problem. To do this, open the Java Console, click
+ the Clear button and select TRACE in the Log level
+ drop down list.
Whilst leaving the console open, perform the
+ task in Jalview that re-creates the problem.
Then you can
+ copy the debug information in the Java Console by clicking on the Copy
+ to clipboard button and then paste that into the Description, or a
+ Comment of your issue.
+
+ For other queries or comments about Jalview, remember you can + contact the Jalview team using email via the + Jalview + discussion list, on Twitter @Jalview, or for technical + discussions, via the Jalview developer's chatroom at + https://gitter.im/jalview/developers. +
+ + +