<title>The Java Console, Logging and Reporting Bugs</title>
</head>
<body>
- <h2>
- <center>
- <strong>The Java Console, Logging and Reporting Bugs</strong>
- </center>
- </h2>
-
- <h3>Logging</h3>
<p>
- Jalview creates logs that can be extremely useful for diagnosing, or help to provide a workaround for, specific problems that you might encounter.
- </p>
- <p>
- The primary place to look for logs is in the <a href="#java_console">Java Console</a> which you can open from within Jalview by going to the <em>Tools</em> menu and checking the box next to <em>Show Java Console</em>. This option is stored in your Jalview preferences file and so is remembered across Jalview sessions.
- </p>
- <p>
- The Java Console will show you information about what the Jalview application is doing (often in the background) whilst it is running.
- </p>
- <p>
- However, it is possible that some early logging information from when Jalview is initially launched, is not shown in the Java Console:
- <br/>
- If you are using a standard desktop version of Jalview installed from one of our install4j installers, then Jalview's initial launch logging can be found in
+ <strong>The Java Console, Logging and Reporting Bugs<br /></strong>
+ </p>
+ <p>Like most programs, Jalview produces a series of messages
+ during its operation, often referred to as 'logs'. These logs can be
+ extremely useful for diagnosing and helping the Jalview developers
+ find a workaround for specific problems that you might encounter.</p>
+ <p>
+ The primary place to look for logs is in the <a href="#java_console">Java
+ Console</a> which you can open from within Jalview by going to the <em>Tools</em>
+ menu and checking the box next to <em>Show Java Console</em>. This
+ option is stored in your Jalview preferences file and so is
+ remembered across Jalview sessions.
+ </p>
+ <p>The Java Console will show you information about what the
+ Jalview application is doing (often in the background) whilst it is
+ running.</p>
+ <p>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:</p>
+ <p>
+ <strong>Jalview Desktop Installations</strong><br />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
<pre>JALVIEW_APP_DIR/launcher.log</pre>
- where <em>JALVIEW_APP_DIR</em> is the directory that Jalview's application was installed into.
- <br/>
- For Jalview 2.11.0 onwards:
+ where
+ <em>JALVIEW_APP_DIR</em> is the directory that Jalview's application
+ was installed into.
+ <br /> For Jalview 2.11.0 onwards:
<ul>
- <li>In Windows this is <em>%APPDATA%\Local\Jalview</em> by default</li>
- <li>In macOS this is <em>/Applications/Jalview.app/Contents/Resources/app</em> by default</li>
- <li>In Linux and other Unix OSes this is <em>~/opt/jalview</em> by default</li>
+ <li>In Windows this is <em>%APPDATA%\Local\Jalview</em> by
+ default
+ </li>
+ <li>In macOS this is <em>/Applications/Jalview.app/Contents/Resources/app</em>
+ by default
+ </li>
+ <li>In Linux and other Unix OSes this is <em>~/opt/jalview</em>
+ by default
+ </li>
</ul>
- <br/>
- Whereas if you are using the Jalview executable jar file (also used by bioconda installations) then the default run class (<em>jalview.bin.Launcher</em> -- a minimised launcher that will set memory and linux dpi settings before re-launching <em>jalview.bin.Jalview</em>), will output logging information to STDOUT and STDERR.
- </p>
-
- <h3><a name="java_console">Java Console and Log Level</a></h3>
- <p>
- The Java Console is opened by selecting <strong>Tools → Show Java Console</strong>. This option is saved across Jalview sessions so you can start Jalview with the Java Console already open by previously quitting Jalview with the Java Console already opened. Selecting <em>Show Java Console</em> in the <em>Tools</em> menu a second time will deselect the option and close the window. Closing the window in your system's usual way will also deselect the option in the <em>Tools</em> menu.
- </p>
- <p>
- The Java Console's text display always shows information about your system and Jalview installation setup, which is followed by messages output from some of the processes that your Jalview session has performed since opening the console.
- </p>
- <p>
- You can control the detail of what appears as output by selecting a <em>Log level</em> using the drop-down list at the bottom left of the console. There are several levels of logging that you can choose from: in decreasing levels of verbosity they are: TRACE, DEBUG, INFO, WARN. By default the level initially chosen is INFO.
- </p>
- <p>
- <strong>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).</strong>
+ <p><strong>Jalview Executable Jar</strong><br/>If you are using the Jalview executable jar file (also
+ used by bioconda and OSX homebrew installations) then the default run class (
+ <em>jalview.bin.Launcher</em> -- a minimised launcher that will set
+ memory and linux dpi settings before re-launching
+ <em>jalview.bin.Jalview</em>), will output logging information to
+ STDOUT and STDERR.
</p>
+
+ <p><strong>
+ <a name="java_console">Java Console and Log Level</a>
+ </strong></p>
+ <p>
+ The Java Console is opened by selecting <strong>Tools
+ → Show Java Console</strong>. 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.
+ </p>
+ <p>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.</p>
+
<p>
- You can change the default log level by editing the Jalview preferenecs file, <em>.jalview_properties</em>, found in your home directory (on Windows: %HOMEPATH%, or the folder above 'My Documents'; on macOS: ~ or /Users/<em>username</em>; on linux/unix: ~ or /home/<em>username</em>), and setting the property <em>logs.Jalview.level</em> to the log level you prefer, e.g.
+ You can temporarily control the detail of what appears as output by
+ selecting a <em>Log level</em> 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).
+ </p>
+ <p>
+ <strong>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).</strong>
+ </p>
+ <p><strong>Permanently changing Jalview's default log level</strong><br/>
+ You can change the default log level by editing the Jalview
+ preferences file, <em>.jalview_properties</em>, found in your home
+ directory (on Windows: %HOMEPATH%, or the folder above 'My
+ Documents'; on macOS: ~ or /Users/<em>username</em>; on linux/unix:
+ ~ or /home/<em>username</em>), and setting the property <em>logs.Jalview.level</em>
+ to the log level you prefer, e.g.
<pre>
logs.Jalview.level=DEBUG
</pre>
<pre>
logs.Axis.level=DEBUG
</pre>
- to get debug information for Jalview's JPred service. The Axis log level cannot be set from within the Java Console.
+ <p>to get debug information for Jalview's JPred service. The Axis log
+ level cannot be set from within the Java Console.
</p>
<p>
- You can set the <em>logs.jalview.level</em> property to a log level not usually presented in the Java Console (though restricted to log levels used by Apache Log4j -- see <a href="https://logging.apache.org/log4j/2.x/manual/customloglevels.html">Log4j Custom Log Levels</a> 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.
+ You can also set the <em>logs.jalview.level</em> property to a log level
+ not usually presented in the Java Console (though restricted to log
+ levels used by Apache Log4j -- see <a
+ href="https://logging.apache.org/log4j/2.x/manual/customloglevels.html">Log4j
+ Custom Log Levels</a> 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.
</p>
<p>
- The <em>Clear</em> 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 <em>Clear</em> button at the bottom of the console will clear
+ all logging messages except for the initial system information which
+ is rewritten to the console.
</p>
<p>
- The <em>Copy to clipboard</em> 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).
+ The <em>Copy to clipboard</em> 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).
</p>
<h3>Reporting Bugs</h3>
<p>
- 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 <a href="https://www.jalview.org/faq">Jalview FAQ</a> to see if this is a known problem and if there is a suggested workaround.
+ 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 <a href="https://www.jalview.org/faq">Jalview FAQ</a> to
+ see if this is a known problem and if there is a suggested
+ workaround.
</p>
<p>
- If there is no FAQ answer covering your problem then you can submit a bug report on the <a href="https://issues.jalview.org/">Jalview Issue Tracker</a>. 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:
+ If there is no FAQ answer covering your problem then you can submit
+ a bug report on the <a href="https://issues.jalview.org/">Jalview
+ Issue Tracker</a>. 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:
</p>
<p>
- Make sure that you set Project to <em>Jalview (JAL)</em>, and Issue Type to <em>Bug</em> or <em>New Feature</em> or <em>Improvement</em> appropriately.<br/>
- Give a one line summary of the issue in the <em>Summary</em>.
- <br/>
- In the <em>Environment</em> text box you can describe the system you are using. This is usually most easily done by opening the Java Console, clicking the <em>Clear</em> button, and then immediately on the <em>Copy to clipboard</em> button, and then pasting the clipboard into the text box.
+ Make sure that you set Project to <em>Jalview (JAL)</em>, and Issue
+ Type to <em>Bug</em> or <em>New Feature</em> or <em>Improvement</em>
+ appropriately.<br /> Give a one line summary of the issue in the <em>Summary</em>.
+ <br /> In the <em>Environment</em> text box you can describe the
+ system you are using. This is usually most easily done by opening
+ the Java Console, clicking the <em>Clear</em> button, and then
+ immediately on the <em>Copy to clipboard</em> button, and then
+ pasting the clipboard into the text box.
</p>
<p>
- You can then give more detailed information about how to recreate the problem in the <em>Description</em> 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 <em>Attachment</em> browse facility to locate them on your computer.
+ You can then give more detailed information about how to recreate
+ the problem in the <em>Description</em> 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 <em>Attachment</em> browse facility to
+ locate them on your computer.
</p>
<p>
- 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 <em>Clear</em> button and select TRACE in the <em>Log level</em> drop down list.
- <br/>
- Whilst leaving the console open, perform the task in Jalview that re-creates the problem.
- <br/>
- Then you can copy the debug information in the Java Console by clicking on the <em>Copy to clipboard</em> button and then paste that into the Description, or a Comment of your issue.
+ 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 <em>Clear</em> button and select TRACE in the <em>Log level</em>
+ drop down list. <br /> Whilst leaving the console open, perform the
+ task in Jalview that re-creates the problem. <br /> Then you can
+ copy the debug information in the Java Console by clicking on the <em>Copy
+ to clipboard</em> button and then paste that into the Description, or a
+ Comment of your issue.
</p>
- <p>For other queries or comments about Jalview, remember you can contact the Jalview team using email via the <a href="https://www.jalview.org/mailman/listinfo/jalview-discuss">Jalview discussion list</a> or on Twitter <a href="https://twitter.com/Jalview/">@Jalview</a>!
+ <p>
+ For other queries or comments about Jalview, remember you can
+ contact the Jalview team using email via the
+ <a href="https://www.jalview.org/mailman/listinfo/jalview-discuss">Jalview
+ discussion list</a>, on Twitter <a
+ href="https://twitter.com/Jalview/">@Jalview</a>, or for technical
+ discussions, via the Jalview developer's chatroom at
+ <a href="https://gitter.im/jalview/developers">https://gitter.im/jalview/developers</a>.
</p>
</body>
git://source.jalview.org / jalview.git / commitdiff