help/help/html/logging.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   5  *
   6  * This file is part of Jalview.
   7  *
   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.
  12  *
  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.
  17  *
  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.
  21  -->
  22 <head>
  23 <title>The Java Console, Logging and Reporting Bugs</title>
  24 </head>
  25 <body>
  26   <p>
  27     <strong>The Java Console, Logging and Reporting Bugs<br /></strong>
  28   </p>
  29   <p>
  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.
  37   </p>
  38   <p>
  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.
  44   </p>
  45   <p>The Java Console will show you information about what the
  46     Jalview application is doing (often in the background) whilst it is
  47     running.</p>
  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>
  52   <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
  56     can be found in
  57   <pre>JALVIEW_APP_DIR/launcher.log</pre>
  58   where
  59   <em>JALVIEW_APP_DIR</em> is the directory that Jalview's application
  60   was installed into.
  61   <br /> For Jalview 2.11.0 onwards:
  62   <ul>
  63     <li>In Windows this is <em>%APPDATA%\Local\Jalview</em> by
  64       default
  65     </li>
  66     <li>In macOS this is <em>/Applications/Jalview.app/Contents/Resources/app</em>
  67       by default
  68     </li>
  69     <li>In Linux and other Unix OSes this is <em>~/opt/jalview</em>
  70       by default
  71     </li>
  72   </ul>
  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
  78   STDOUT and STDERR.
  79   </p>
  80
  81   <p><strong>
  82     <a name="java_console">Java Console and Log Level</a>
  83   </strong></p>
  84   <p>
  85     The Java Console is opened by selecting <strong>Tools
  86       &rarr; 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
  90     console window.
  91   </p>
  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
  97     Jalview.</p>
  98
  99   <p>
 100     You can temporarily control the detail of what appears as output by
 101     selecting a <em>Log level</em> using the drop-down list at the
 102     bottom left of the console. There are several levels to choose from:
 103     The most verbose is TRACE, followed by DEBUG, INFO, WARN. When the
 104     Console is opened, the default level will be chosen (INFO).
 105   </p>
 106   <p>
 107     <strong>Note! If you change the log level in the Java
 108       Console, this change will only persist for as long as the console
 109       is open. Once you close the console the log level will revert back
 110       to what it had been when you opened the console (usually INFO).</strong>
 111   </p>
 112   <p><strong>Permanently changing Jalview's default log level</strong><br/>
 113     You can change the default log level by editing the Jalview
 114     preferences file, <em>.jalview_properties</em>, found in your home
 115     directory (on Windows: %HOMEPATH%, or the folder above 'My
 116     Documents'; on macOS: ~ or /Users/<em>username</em>; on linux/unix:
 117     ~ or /home/<em>username</em>), and setting the property <em>logs.Jalview.level</em>
 118     to the log level you prefer, e.g.
 119   <pre>
 120   logs.Jalview.level=DEBUG
 121   </pre>
 122   You can also set the property
 123   <pre>
 124   logs.Axis.level=DEBUG
 125   </pre>
 126   <p>to get debug information for Jalview's JPred service. The Axis log
 127   level cannot be set from within the Java Console.
 128   </p>
 129   <p>
 130     You can also set the <em>logs.jalview.level</em> property to a log level
 131     not usually presented in the Java Console (though restricted to log
 132     levels used by Apache Log4j -- see <a
 133       href="https://logging.apache.org/log4j/2.x/manual/customloglevels.html">Log4j
 134       Custom Log Levels</a> for details of the standard log levels
 135     available). Jalview does not currently define any custom log levels.
 136     If you do set the property with a log level that is normally not
 137     visible in the Java Console this should be respected and visibly
 138     selected when you open the console.
 139   </p>
 140   <p>
 141     The <em>Clear</em> button at the bottom of the console will clear
 142     all logging messages except for the initial system information which
 143     is rewritten to the console.
 144   </p>
 145   <p>
 146     The <em>Copy to clipboard</em> button at the bottom right of the
 147     console will copy all of the text in the console to your system
 148     clipboard, ready to paste into another application (e.g. email
 149     composer or issue tracker).
 150   </p>
 151
 152   <p><strong><a name="reportingbugs">Reporting Bugs</a></strong></p>
 153
 154   <p>
 155     If you come across a problem in Jalview where something is not
 156     working as described, or how you think it should, you should first
 157     check the <a href="https://www.jalview.org/faq">Jalview FAQ</a> to
 158     see if this is a known problem and if there is a suggested
 159     workaround.
 160   </p>
 161   <p>
 162     If there is no FAQ answer covering your problem then you can submit
 163     a bug report on the <a href="https://issues.jalview.org/">Jalview
 164       Issue Tracker</a>. It is good practice to search the issue tracker
 165     first to see if the issue has already been reported. If an issue
 166     already exists please continue to add your own comments to the issue
 167     which may well help narrow down the problem, if not then you can
 168     create an account and submit a new bug report:
 169   </p>
 170   <p>
 171     Make sure that you set Project to <em>Jalview (JAL)</em>, and Issue
 172     Type to <em>Bug</em> or <em>New Feature</em> or <em>Improvement</em>
 173     appropriately.<br /> Give a one line summary of the issue in the <em>Summary</em>.
 174     <br /> In the <em>Environment</em> text box you can describe the
 175     system you are using. This is usually most easily done by opening
 176     the Java Console, clicking the <em>Clear</em> button, and then
 177     immediately on the <em>Copy to clipboard</em> button, and then
 178     pasting the clipboard into the text box.
 179   </p>
 180   <p>
 181     You can then give more detailed information about how to recreate
 182     the problem in the <em>Description</em> text box. If you want to
 183     attach any screenshots or example alignment files that demonstrate
 184     the problem then you can drag them to the Create Issue dialog in
 185     your browser, or use the <em>Attachment</em> browse facility to
 186     locate them on your computer.
 187   </p>
 188
 189   <p>
 190     To help the Jalview team with diagnosing a particular issue, it is
 191     really helpful if you can also add more detailed logs output whilst
 192     re-creating the problem. To do this, open the Java Console, click
 193     the <em>Clear</em> button and select TRACE in the <em>Log level</em>
 194     drop down list. <br /> Whilst leaving the console open, perform the
 195     task in Jalview that re-creates the problem. <br /> Then you can
 196     copy the debug information in the Java Console by clicking on the <em>Copy
 197       to clipboard</em> button and then paste that into the Description, or a
 198     Comment of your issue.
 199   </p>
 200
 201   <p>
 202     For other queries or comments about Jalview, remember you can
 203     contact the Jalview team using email via the
 204     <a href="https://www.jalview.org/mailman/listinfo/jalview-discuss">Jalview
 205       discussion list</a>, on Twitter <a
 206       href="https://twitter.com/Jalview/">@Jalview</a>, or for technical
 207     discussions, via the Jalview developer's chatroom at
 208     <a href="https://gitter.im/jalview/developers">https://gitter.im/jalview/developers</a>.
 209   </p>
 210
 211 </body>
 212 </html>