website/man_pages_old/man_stats.jsp

   1 <%--<?xml version="1.0" encoding="ISO-8859-1" ?>--%>
   2 <%--<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>--%>
   3
   4 <%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
   5 <%@ taglib uri="http://java.sun.com/jsp/jstl/functions" prefix="fn" %>
   6 <%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt" %>
   7 <%@ taglib uri="http://displaytag.sf.net" prefix="dt" %>
   8
   9
  10 <c:import url="../template_header.jsp" >
  11     <c:param name="title">Documentation</c:param>
  12 </c:import>
  13
  14 <ol class="breadcrumb">
  15     <li><a href="${pageContext.request.contextPath}/index.jsp">Home</a></li>
  16     <li><a href="man_docs.jsp">Documentation</a></li>
  17     <li class="active"><a href="man_server_dev.jsp">Develop JABAWS</a></li>
  18 </ol>
  19 <div class="row">
  20     <div class="col-md-12">
  21         <div class="panel panel-default">
  22             <div class="panel panel-heading">
  23                 <h1 class="panel-title">JABAWS Usage Statistics</h1>
  24             </div>
  25             <div class="panel-body">
  26                 <!--<h4>JABAWS Server Virtual Appliance</h4>-->
  27                 <ul>
  28                     <li><a href="#usage_sum">Summary of Usage</a></li>
  29                     <li><a href="#helpUsageStats">Authentication</a></li>
  30                     <li><a href="#detailed_usage">Detailed Usage Statistic </a></li>
  31                     <li><a href="#job_list">Job List</a></li>
  32                     <li><a href="#job_dir">Single Job Directory Content </a></li>
  33                     <li><a href="#conf_tomcat_user">Configuring a privileged   access for Tomcat web application server</a></li>
  34                     <li><a href="#exec_stat_conf">Configuring JABAWS execution statistics</a></li>
  35                 </ul>
  36                 <!--<p class="justify">-->
  37                 <!--</p>-->
  38             </div>
  39         </div>
  40     </div>
  41 </div>
  42 <div class="row" id="usage_sum">
  43     <div class="col-md-12">
  44         <div class="panel panel-default">
  45             <div class="panel panel-heading">
  46                 <h1 class="panel-title">Summary of Usage</h1>
  47             </div>
  48             <div class="panel-body">
  49                 <p class="justify">
  50                     JABAWS comes with a web application for visualizing usage statistics.
  51                     The screenshot below shows the main page of this application.
  52                     The individual month is linked to detailed usage statistics (described later).
  53                     Please note, that the links to the detailed monthly statistics are only
  54                     available for authenticated users in the role
  55                     <em2>admin</em2>. There is a link at the bottom of the
  56                     page that lets you login, if you have not done so.
  57                 </p>
  58                 <p class="justify">
  59                     If you are using JABAWS VA (Virtual Appliance) then the username is
  60                     <em2>jabaws</em2> and password is not defined,
  61                     i.e. empty.
  62                 </p>
  63                 <p class="justify">
  64                     If you have deployed a JABAWS WAR file, then please see the
  65                     <a href="#conf_tomcat_user">configuring privileged access for Tomcat web
  66                         application server</a> section for further details.
  67                 </p>
  68
  69                 <p><img src="../static/img/usage_statistics_main.gif" alt="JABAWS usage statistics"
  70                         width="608" height="318" />
  71                 </p>
  72                 <p class="justify">
  73                     The table contains the number of jobs processed by JABAWS per month, for
  74                     the whole period when the statistics was collected.
  75                 </p>
  76                 <p>For each month the table contains the following information.</p>
  77                 <ul>
  78                     <li>Month - the period of time for which statistics is displayed. For example
  79                         Jan 2011 means period of time from the first of January to the first of
  80                         February</li>
  81                     <li>Total - the total number of jobs accepted by JABAWS</li>
  82                     <li>Incomplete - the number of jobs for which the result file was not
  83                         found or was empty excluding cancelled</li>
  84                     <li>Cancelled - the number of jobs cancelled by the user</li>
  85                     <li>Abandoned - the number of jobs which result(s) were not collected</li>
  86                 </ul>
  87                 <p>The summary for each column is displayed in the last row of the table.</p>
  88
  89                 <p class="text-right">
  90                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
  91                 </p>
  92             </div>
  93         </div>
  94     </div>
  95 </div>
  96 <div class="row" id="helpUsageStats">
  97     <div class="col-md-12">
  98         <div class="panel panel-default">
  99             <div class="panel panel-heading">
 100                 <h1 class="panel-title">Authentication</h1>
 101             </div>
 102             <div class="panel-body">
 103                 <p class="justify">
 104                     Authentication lets you see the detailed usage statistics.
 105                     If you are using JABAWS VA (Virtual Appliance) then the
 106                     username is <em2>jabaws</em2> and
 107                     password is not defined, i.e. empty. In other cases you need
 108                     to ask your system administrator for it.
 109                 </p>
 110                 <p class="text-right">
 111                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 112                 </p>
 113             </div>
 114         </div>
 115     </div>
 116 </div>
 117 <div class="row" id="detailed_usage">
 118     <div class="col-md-12">
 119         <div class="panel panel-default">
 120             <div class="panel panel-heading">
 121                 <h1 class="panel-title">Detailed Usage Statistic</h1>
 122             </div>
 123             <div class="panel-body">
 124                 <p class="justify">
 125                     Detailed execution statistics for each month is available for
 126                     authenticated users only.
 127                 </p>
 128                 <p><img src="../static/img/usage_statistics_month.gif" alt="JABAWS one month usage statistics"
 129                         width="670" height="902" />
 130                 </p>
 131                 <p>Each table contains the number of jobs processed by JABAWS during the period of
 132                     time specified in the title:</p>
 133                 <ul>
 134                     <li>The &quot;All Jobs&quot; table contains the summary of all jobs</li>
 135                     <li>&quot;Local Jobs&quot; table - contains the summary of the jobs calculated by the local engine</li>
 136                     <li>&quot;Cluster Jobs&quot; table - contains the summary of the jobs calculated by the cluster</li>
 137                 </ul>
 138                 Each table contains the following information for each web service:
 139                 <ul>
 140                     <li>Total - the total number of jobs accepted by a particular JABA service</li>
 141                     <li>Incomplete - the number of jobs for which the result file was not found or was empty excluding cancelled</li>
 142                     <li>Cancelled - the number of jobs cancelled by the user</li>
 143                     <li>Abandoned - the number of jobs which result(s) were not collected</li>
 144                 </ul>
 145                 <p class="text-right">
 146                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 147                 </p>
 148             </div>
 149         </div>
 150     </div>
 151 </div>
 152 <div class="row" id="job_list">
 153     <div class="col-md-12">
 154         <div class="panel panel-default">
 155             <div class="panel panel-heading">
 156                 <h1 class="panel-title">Job List</h1>
 157             </div>
 158             <div class="panel-body">
 159                 <p class="justify">
 160                     Please note that if you deployed JABAWS WAR, in order to be able to
 161                     navigate to the job directory from this view, the application server may
 162                     need to be configured. Please see
 163                     <a href="#exec_stat_conf">Configuring JABAWS execution statistics</a> section
 164                     for further details.
 165                 </p>
 166                 <p><img src="../static/img/usage_statistics_details.gif" alt="JABAWS - job list" width="917" height="198" /> </p>
 167                 <p>Columns: </p>
 168                 <ul>
 169                     <li>JobID - the JABAWS job id, unique for every job</li>
 170                     <li>Cluster JobID - cluster job id</li>
 171                     <li>InputSize - input size in bytes</li>
 172                     <li>ResultSize - result size in bytes</li>
 173                     <li>Runtime (s) - job's runtime in seconds</li>
 174                     <li>Start time (s)- job's start time and date</li>
 175                     <li>Finish time (s)- job's finish time and date</li>
 176                     <li>isCancelled - whether the job was cancelled</li>
 177                     <li>isCollected - whether the job was collected. False for the jobs
 178                         that has been initiated but which results has never been retrieved</li>
 179                     <li>isFinished - whether the job has finished. This does not necessarily
 180                         mean that the job has produced the result. The job can sometime finish
 181                         in failure</li>
 182                 </ul>
 183                 <p class="text-right">
 184                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 185                 </p>
 186             </div>
 187         </div>
 188     </div>
 189 </div>
 190 <div class="row" id="job_dir">
 191     <div class="col-md-12">
 192         <div class="panel panel-default">
 193             <div class="panel panel-heading">
 194                 <h1 class="panel-title">Single Job Directory Content</h1>
 195             </div>
 196             <div class="panel-body">
 197                 <p class="justify">
 198                     <img src="../static/img/usage_statistics_job_details.gif" alt="JABAWS- job details"
 199                          width="600" height="340" /></p>
 200                 <p>
 201                     STARTED and FINISHED files contain Unix timestamp - when the job was started and
 202                     completed respectively. STARTED is replaced by SUBMITTED if the job has been
 203                     submitted to the cluster, as opposed to executed locally, on the server.
 204                 </p>
 205                 <p class="justify">
 206                     COLLECTED file is empty and indicates that the job results were collected by the
 207                     user. Due to asynchronous nature of the job it is possible that the job
 208                     was started and finished, but the results has never been requested.
 209                 </p>
 210                 <p class="justify">
 211                     RunnerConfig.xml file contains a complete description of the job and JABAWS
 212                     can restart the job based on this description.
 213                 </p>
 214                 <p class="justify">
 215                     procError.txt and procOutput.txt files  contains the content of the standard
 216                     out and standard error streams of the process.
 217                 </p>
 218                 <p>result.txt file contains the results. </p>
 219                 <p>input.txt file contains input into the process. </p>
 220                 <p>
 221                     There are maybe other files depending on the nature of the job, but the one
 222                     described above will be present in most cases. In this example, stat.log file
 223                     stories the execution statistics generated by (clustal executable in this example)
 224                     process.
 225                 </p>
 226                 <p class="justify">
 227                     If you have deployed JABAWS WAR file or made changes to JABAWS configuration
 228                     you may need to make a few changes to the Tomcat configuration to be able to see
 229                     the content of the job directory. Please see
 230                     <a href="#exec_stat_conf">Configuring JABAWS execution statistics</a>
 231                     section for further details.
 232                 </p>
 233                 <p class="text-right">
 234                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 235                 </p>
 236             </div>
 237         </div>
 238     </div>
 239 </div>
 240 <div class="row" id="exec_stat_conf">
 241     <div class="col-md-12">
 242         <div class="panel panel-default">
 243             <div class="panel panel-heading">
 244                 <h1 class="panel-title">Configuring JABAWS execution statistics</h1>
 245             </div>
 246             <div class="panel-body">
 247                 <p class="justify">
 248                     JABAWS execution statistics is a multi-component system. First is a crawler whose job
 249                     is to collect and preprocess the statistics from the job temporary directories and
 250                     record the collected statistics into the database. The second part of the system is
 251                     a web application whose job is to visualise the statistics from the database.
 252                 </p>
 253                 <p class="justify">
 254                     It is possible to enable/disable the statistics collector by changing the
 255                     following properties in the conf/Cluster.engine.properties and
 256                     conf/Local.engine.properties files.
 257                 </p>
 258                 <pre><code class="bash"># Enable/disable cluster statistics collector true = enable, false = disable
 259 cluster.stat.collector.enable=false
 260 # Maximum amount of time the job is considered be running in hours. Optional defaults to 7 days (168h)
 261 cluster.stat.maxruntime=24</code></pre>
 262                 <pre><code class="bash"># Enable/disable cluster statistics collector true = enable, false = disable
 263 local.stat.collector.enable=true
 264 # Maximum amount of time the job is considered to be running in hours. Optional defaults to 24 hours
 265 local.stat.maxruntime=6</code></pre>
 266                 <p class="justify">
 267                     If the statistics collector is enabled then the crawler starts automatically
 268                     soon after (10 minutes for local engine, and 60 minutes for cluster engine)
 269                     the JABAWS web application and will be collecting the execution statistics
 270                     every 24 hours after the start.
 271                 </p>
 272                 <p class="justify">
 273                     The details of the job are only available if the job temporary directory
 274                     is located within a JABAWS web application. If not, the system
 275                     administrator can create a symbolic link pointing to the temporary
 276                     job directories outside of a web application and configure the
 277                     application server to allow navigation to the links. For the Tomcat
 278                     application server the context configuration file should be created and
 279                     copied to the &lt;TOMCAT_ROOT&gt;/conf/Catalina/localhost directory. The
 280                     name of the file should be the same as the web application context name,
 281                     for example &quot;<em2>jabaws.xml</em2>&quot; for
 282                     jabaws. Where the TOMCAT_ROOT is the location of the Tomcat web application
 283                     server. Here is an example of such a file:
 284                 </p>
 285                 <pre><code class="xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
 286 &lt;Context antiResourceLocking=&quot;false&quot; privileged=&quot;true&quot; allowLinking=&quot;true&quot;/&gt;</code></pre>
 287                 <p>
 288                     The key option here is this:
 289                     <em2>allowLinking=&quot;true&quot;</em2>.
 290                     Please also make sure that you have defined the user in role
 291                     &quot;<em2>admin</em2>&quot; as described
 292                     <a href="#conf_tomcat_user">below</a>.
 293                 </p>
 294                 <p class="text-right">
 295                     <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
 296                 </p>
 297             </div>
 298         </div>
 299     </div>
 300 </div>
 301 <div class="row" id="conf_tomcat_user">
 302     <div class="col-md-12">
 303         <div class="panel panel-default">
 304             <div class="panel panel-heading">
 305                 <h1 class="panel-title">Configuring a privileged
 306                     access for Tomcat web application server</h1>
 307             </div>
 308             <div class="panel-body">
 309                 <p class="justify">
 310                     Access to configuration files, detailed job execution statistics and job
 311                     directories are allowed only for authenticated users in role
 312                     &quot;<em2>admin</em2>&quot;.
 313                 </p>
 314                 <p>If you use Tomcat, then the simplest way to set up privileged
 315                     access is to use a plain text configuration file
 316                     <em2>conf/tomcat-user.xml</em2>. Here is an example
 317                     of such configuration file defining user
 318                     &quot;<em2>peter</em2>&quot; in role
 319                     &quot;<em2>admin</em2>&quot;.
 320                     <pre><code class="xml">&lt;tomcat-users&gt;
 321 &lt;role rolename=&quot;admin&quot;/&gt;
 322 &lt;user username=&quot;peter&quot; password=&quot;your password here &quot; roles=&quot;admin&quot;/&gt;
 323 &lt;/tomcat-users&gt;</code></pre>
 324                 <p>For more information on users and roles please consult Apache-Tomcat help pages.</p>
 325             </div>
 326         </div>
 327     </div>
 328 </div>
 329
 330 <jsp:include page="../template_footer.jsp" />