3 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4 * Copyright (C) $$Year-Rel$$ The Jalview Authors
6 * This file is part of Jalview.
8 * Jalview is free software: you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License
10 * as published by the Free Software Foundation, either version 3
11 * of the License, or (at your option) any later version.
13 * Jalview is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty
15 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
16 * PURPOSE. See the GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
20 * The Jalview Authors are detailed in the 'AUTHORS' file.
23 <title>The Java Console, Logging and Reporting Bugs</title>
27 <strong>The Java Console, Logging and Reporting Bugs<br /></strong>
30 Like most programs, Jalview contains bugs, despite our best efforts.
31 However, Jalview also produces a series of messages during its
32 operation, often referred to as 'logs'. These logs provide a record
33 of Jalview's operation. They can also be extremely useful when <a
34 href="#reportingbugs">reporting bugs</a>, since they help the
35 Jalview developers diagnose and find a workaround for specific
36 problems that you might encounter.
39 The primary place to look for logs is in the <a href="#java_console">Java
40 Console</a> which you can open from within Jalview by going to the <em>Tools</em>
41 menu and checking the box next to <em>Show Java Console</em>. This
42 option is stored in your Jalview preferences file and so is
43 remembered across Jalview sessions.
45 <p>The Java Console will show you information about what the
46 Jalview application is doing (often in the background) whilst it is
48 <p>However, when tracking down problems preventing Jalview from
49 starting up properly, you need to look at the startup logs - which
50 are not shown in the Jalview Console. The location of these depends
51 on how you launched Jalview:</p>
53 <strong>Jalview Desktop Installation Launch Logs</strong><br />If you are using
54 a standard desktop version of Jalview installed from one of our
55 install4j installers, then messages about Jalview's initial launch
57 <pre>JALVIEW_APP_DIR/launcher.log</pre>
59 <em>JALVIEW_APP_DIR</em> is the directory that Jalview's application
61 <br /> For Jalview 2.11.0 onwards:
63 <li>In Windows this is <em>%APPDATA%\Local\Jalview</em> by
66 <li>In macOS this is <em>/Applications/Jalview.app/Contents/Resources/app</em>
69 <li>In Linux and other Unix OSes this is <em>~/opt/jalview</em>
73 <p><strong>Jalview Executable Jar Launch Logs</strong><br/>If you are using the Jalview executable jar file (also
74 used by bioconda and OSX homebrew installations) then the default run class (
75 <em>jalview.bin.Launcher</em> -- a minimised launcher that will set
76 memory and linux dpi settings before re-launching
77 <em>jalview.bin.Jalview</em>), will output logging information to
82 <a name="java_console">Java Console and Log Level</a>
85 The Java Console is opened by selecting <strong>Tools
86 → Show Java Console</strong>. The visibility of the console is stored
87 in your preferences, so if you quit Jalview with the console open,
88 it will be shown the next time you start Jalview. You can close the
89 console by selecting the same menu option again, or just closing the
92 <p>The Java Console's text display always shows information about
93 your system and Jalview installation details. The rest are the most
94 recent messages output during your Jalview session. Some messages
95 are only captured by the console when it is open, so to get a full
96 log for debugging a problem, enable the console and then restart
100 Jalview logging will automatically scroll the text in the Java Console
101 but if you want to examine a particular part of the logs whilst logging
102 is still going on you can click on any part of the text area to
103 stop this behaviour. A border should appear arround the
104 text area to signify that autoscroll has been turned off. You can
105 toggle the autoscroll behaviour on and off by clicking again on the
109 You can temporarily control the detail of what appears as output by
110 selecting a <em>Log level</em> using the drop-down list at the
111 bottom left of the console. There are several levels to choose from:
112 The most verbose is TRACE, followed by DEBUG, INFO, WARN. When the
113 Console is opened, the default level will be chosen (INFO).
116 <strong>Note! If you change the log level in the Java
117 Console, this change will only persist for as long as the console
118 is open. Once you close the console the log level will revert back
119 to what it had been when you opened the console (usually INFO).</strong>
121 <p><strong>Permanently changing Jalview's default log level</strong><br/>
122 You can change the default log level by editing the Jalview
123 preferences file, <em>.jalview_properties</em>, found in your home
124 directory (on Windows: %HOMEPATH%, or the folder above 'My
125 Documents'; on macOS: ~ or /Users/<em>username</em>; on linux/unix:
126 ~ or /home/<em>username</em>), and setting the property <em>logs.Jalview.level</em>
127 to the log level you prefer, e.g.
129 logs.Jalview.level=DEBUG
131 You can also set the property
133 logs.Axis.level=DEBUG
135 <p>to get debug information for Jalview's JPred service. The Axis log
136 level cannot be set from within the Java Console.
139 You can also set the <em>logs.jalview.level</em> property to a log level
140 not usually presented in the Java Console (though restricted to log
141 levels used by Apache Log4j -- see <a
142 href="https://logging.apache.org/log4j/2.x/manual/customloglevels.html">Log4j
143 Custom Log Levels</a> for details of the standard log levels
144 available). Jalview does not currently define any custom log levels.
145 If you do set the property with a log level that is normally not
146 visible in the Java Console this should be respected and visibly
147 selected when you open the console.
150 The <em>Clear</em> button at the bottom of the console will clear
151 all logging messages except for the initial system information which
152 is rewritten to the console.
155 The <em>Copy to clipboard</em> button at the bottom right of the
156 console will copy all of the text in the console to your system
157 clipboard, ready to paste into another application (e.g. email
158 composer or issue tracker).
161 <p><strong><a name="reportingbugs">Reporting Bugs</a></strong></p>
164 If you come across a problem in Jalview where something is not
165 working as described, or how you think it should, you should first
166 check the <a href="https://www.jalview.org/help/faq">Jalview FAQ</a> to
167 see if this is a known problem and if there is a suggested
171 If there is no FAQ answer covering your problem then you can submit
172 a bug report on the <a href="https://issues.jalview.org/">Jalview
173 Issue Tracker</a>. It is good practice to search the issue tracker
174 first to see if the issue has already been reported. If an issue
175 already exists please continue to add your own comments to the issue
176 which may well help narrow down the problem, if not then you can
177 create an account and submit a new bug report:
180 Make sure that you set Project to <em>Jalview (JAL)</em>, and Issue
181 Type to <em>Bug</em> or <em>New Feature</em> or <em>Improvement</em>
182 appropriately.<br /> Give a one line summary of the issue in the <em>Summary</em>.
183 <br /> In the <em>Environment</em> text box you can describe the
184 system you are using. This is usually most easily done by opening
185 the Java Console, clicking the <em>Clear</em> button, and then
186 immediately on the <em>Copy to clipboard</em> button, and then
187 pasting the clipboard into the text box.
190 You can then give more detailed information about how to recreate
191 the problem in the <em>Description</em> text box. If you want to
192 attach any screenshots or example alignment files that demonstrate
193 the problem then you can drag them to the Create Issue dialog in
194 your browser, or use the <em>Attachment</em> browse facility to
195 locate them on your computer.
199 To help the Jalview team with diagnosing a particular issue, it is
200 really helpful if you can also add more detailed logs output whilst
201 re-creating the problem. To do this, open the Java Console, click
202 the <em>Clear</em> button and select TRACE in the <em>Log level</em>
203 drop down list. <br /> Whilst leaving the console open, perform the
204 task in Jalview that re-creates the problem. <br /> Then you can
205 copy the debug information in the Java Console by clicking on the <em>Copy
206 to clipboard</em> button and then paste that into the Description, or a
207 Comment of your issue.
211 For other queries or comments about Jalview, remember you can
212 contact the Jalview team using email via the
213 <a href="https://discourse.jalview.org/">Jalview
214 Discussion Forum</a>, on Twitter <a
215 href="https://twitter.com/Jalview/">@Jalview</a>, or for technical
216 discussions, via the Jalview developer's chatroom at
217 <a href="https://gitter.im/jalview/developers">https://gitter.im/jalview/developers</a>.