website/docs/stats.html

   1
   2
   3 <!DOCTYPE html>
   4 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
   5 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
   6 <head>
   7   <meta charset="utf-8">
   8
   9   <meta name="viewport" content="width=device-width, initial-scale=1.0">
  10
  11   <title>Usage Statistics &mdash; JABAWS 2.2 documentation</title>
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29     <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  30
  31
  32
  33
  34
  35         <link rel="index" title="Index"
  36               href="genindex.html"/>
  37         <link rel="search" title="Search" href="search.html"/>
  38     <link rel="top" title="JABAWS 2.2 documentation" href="index.html"/>
  39         <link rel="next" title="Citations" href="citations.html"/>
  40         <link rel="prev" title="For Developers" href="develop.html"/>
  41
  42
  43   <script src="_static/js/modernizr.min.js"></script>
  44
  45 </head>
  46
  47 <body class="wy-body-for-nav" role="document">
  48
  49
  50   <div class="wy-grid-for-nav">
  51
  52
  53     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
  54       <div class="wy-side-scroll">
  55         <div class="wy-side-nav-search">
  56
  57
  58
  59             <a href="index.html" class="icon icon-home"> JABAWS
  60
  61
  62
  63           </a>
  64
  65
  66
  67
  68               <div class="version">
  69                 2.2
  70               </div>
  71
  72
  73
  74
  75 <div role="search">
  76   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
  77     <input type="text" name="q" placeholder="Search docs" />
  78     <input type="hidden" name="check_keywords" value="yes" />
  79     <input type="hidden" name="area" value="default" />
  80   </form>
  81 </div>
  82
  83
  84         </div>
  85
  86         <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
  87
  88
  89
  90
  91
  92
  93               <p class="caption"><span class="caption-text">Contents:</span></p>
  94 <ul class="current">
  95 <li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting Started</a></li>
  96 <li class="toctree-l1"><a class="reference internal" href="included_tools.html">Included Tools</a></li>
  97 <li class="toctree-l1"><a class="reference internal" href="client.html">Command Line Client (CLI)</a></li>
  98 <li class="toctree-l1"><a class="reference internal" href="war.html">Web Application Archive (WAR)</a></li>
  99 <li class="toctree-l1"><a class="reference internal" href="va.html">Virtual Appliance (VA)</a></li>
 100 <li class="toctree-l1"><a class="reference internal" href="advanced.html">Advanced Usage</a></li>
 101 <li class="toctree-l1"><a class="reference internal" href="develop.html">For Developers</a></li>
 102 <li class="toctree-l1 current"><a class="current reference internal" href="#">Usage Statistics</a><ul>
 103 <li class="toctree-l2"><a class="reference internal" href="#detailed-view">Detailed View</a></li>
 104 <li class="toctree-l2"><a class="reference internal" href="#job-list">Job List</a></li>
 105 <li class="toctree-l2"><a class="reference internal" href="#job-directory-contents">Job Directory Contents</a></li>
 106 <li class="toctree-l2"><a class="reference internal" href="#configuring-jabaws-execution-statistics">Configuring JABAWS execution statistics</a></li>
 107 <li class="toctree-l2"><a class="reference internal" href="#configuring-a-privileged-access-for-tomcat-web-application-server">Configuring a privileged access for Tomcat web application server</a></li>
 108 </ul>
 109 </li>
 110 <li class="toctree-l1"><a class="reference internal" href="citations.html">Citations</a></li>
 111 <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
 112 </ul>
 113
 114
 115
 116         </div>
 117       </div>
 118     </nav>
 119
 120     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
 121
 122
 123       <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
 124
 125           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
 126           <a href="index.html">JABAWS</a>
 127
 128       </nav>
 129
 130
 131
 132       <div class="wy-nav-content">
 133         <div class="rst-content">
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150 <div role="navigation" aria-label="breadcrumbs navigation">
 151
 152   <ul class="wy-breadcrumbs">
 153
 154       <li><a href="index.html">Docs</a> &raquo;</li>
 155
 156       <li>Usage Statistics</li>
 157
 158
 159       <li class="wy-breadcrumbs-aside">
 160
 161
 162             <a href="_sources/stats.rst.txt" rel="nofollow"> View page source</a>
 163
 164
 165       </li>
 166
 167   </ul>
 168
 169
 170   <hr/>
 171 </div>
 172           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
 173            <div itemprop="articleBody">
 174
 175   <div class="section" id="usage-statistics">
 176 <h1>Usage Statistics<a class="headerlink" href="#usage-statistics" title="Permalink to this headline">¶</a></h1>
 177 <p>JABAWS comes with a web application for visualizing usage statistics. The screenshot below shows the main page of this application. The individual month is linked to detailed usage statistics (described later). Please note, that the links to the detailed monthly statistics are only available for authenticated users in the role admin. There is a link at the bottom of the page that lets you login, if you have not done so.</p>
 178 <p>If you are using JABAWS VA (Virtual Appliance) then the username is <em>jabaws</em> and password is not defined, i.e. empty.</p>
 179 <p>If you have deployed a JABAWS WAR file, then please see the <a class="reference external" href="stats.htmll#configuring-a-privileged-access-for-tomcat-web-application-server">configuring privileged access</a> for Tomcat web application server section for further details.</p>
 180 <a class="reference internal image-reference" href="_images/usage_statistics_main.gif"><img alt="_images/usage_statistics_main.gif" class="align-left" src="_images/usage_statistics_main.gif" style="width: 608.0px; height: 318.0px;" /></a>
 181 <p>The table contains the number of jobs processed by JABAWS per month, for the whole period when the statistics was collected.</p>
 182 <p>For each month the table contains the following information.</p>
 183 <ul class="simple">
 184 <li>Month - the period of time for which statistics is displayed. For example Jan 2011 means period of time from the first of January to the first of February</li>
 185 <li>Total - the total number of jobs accepted by JABAWS</li>
 186 <li>Incomplete - the number of jobs for which the result file was not found or was empty excluding cancelled</li>
 187 <li>Cancelled - the number of jobs cancelled by the user</li>
 188 <li>Abandoned - the number of jobs which result(s) were not collected</li>
 189 </ul>
 190 <p>The summary for each column is displayed in the last row of the table.</p>
 191 <hr class="docutils" />
 192 <div class="section" id="detailed-view">
 193 <span id="stat-details"></span><h2>Detailed View<a class="headerlink" href="#detailed-view" title="Permalink to this headline">¶</a></h2>
 194 <p>Detailed execution statistics for each month is available for authenticated users only.</p>
 195 <a class="reference internal image-reference" href="_images/usage_statistics_month.gif"><img alt="_images/usage_statistics_month.gif" class="align-left" src="_images/usage_statistics_month.gif" style="width: 670.0px; height: 902.0px;" /></a>
 196 <p>Each table contains the number of jobs processed by JABAWS during the period of time specified in the title:</p>
 197 <ul class="simple">
 198 <li>The &#8220;All Jobs&#8221; table contains the summary of all jobs</li>
 199 <li>&#8220;Local Jobs&#8221; table - contains the summary of the jobs calculated by the local engine</li>
 200 <li>&#8220;Cluster Jobs&#8221; table - contains the summary of the jobs calculated by the cluster</li>
 201 </ul>
 202 <p>Each table contains the following information for each web service:</p>
 203 <ul class="simple">
 204 <li>Total - the total number of jobs accepted by a particular JABA service</li>
 205 <li>Incomplete - the number of jobs for which the result file was not found or was empty excluding cancelled</li>
 206 <li>Cancelled - the number of jobs cancelled by the user</li>
 207 <li>Abandoned - the number of jobs which result(s) were not collected</li>
 208 </ul>
 209 <hr class="docutils" />
 210 </div>
 211 <div class="section" id="job-list">
 212 <span id="stat-jobs"></span><h2>Job List<a class="headerlink" href="#job-list" title="Permalink to this headline">¶</a></h2>
 213 <p>Please note that if you deployed JABAWS WAR, in order to be able to navigate to the job directory from this view, the application server may need to be configured. Please see the <a class="reference external" href="stats.html#configuring-jabaws-execution-statistics">Configuring JABAWS execution statistics</a> section for further details.</p>
 214 <a class="reference internal image-reference" href="_images/usage_statistics_details.gif"><img alt="_images/usage_statistics_details.gif" class="align-left" src="_images/usage_statistics_details.gif" style="width: 917.0px; height: 198.0px;" /></a>
 215 <p>Columns:</p>
 216 <ul class="simple">
 217 <li>JobID - the JABAWS job id, unique for every job</li>
 218 <li>Cluster JobID - cluster job id</li>
 219 <li>InputSize - input size in bytes</li>
 220 <li>ResultSize - result size in bytes</li>
 221 <li>Runtime (s) - job&#8217;s runtime in seconds</li>
 222 <li>Start time (s)- job&#8217;s start time and date</li>
 223 <li>Finish time (s)- job&#8217;s finish time and date</li>
 224 <li>isCancelled - whether the job was cancelled</li>
 225 <li>isCollected - whether the job was collected. False for the jobs that has been initiated but which results has never been retrieved</li>
 226 <li>isFinished - whether the job has finished. This does not necessarily mean that the job has produced the result. The job can sometime finish in failure</li>
 227 </ul>
 228 <hr class="docutils" />
 229 </div>
 230 <div class="section" id="job-directory-contents">
 231 <span id="stat-dir-contents"></span><h2>Job Directory Contents<a class="headerlink" href="#job-directory-contents" title="Permalink to this headline">¶</a></h2>
 232 <a class="reference internal image-reference" href="_images/usage_statistics_job_details.gif"><img alt="_images/usage_statistics_job_details.gif" class="align-left" src="_images/usage_statistics_job_details.gif" style="width: 644.4px; height: 378.0px;" /></a>
 233 <p>STARTED and FINISHED files contain Unix timestamp - when the job was started and completed respectively. STARTED is replaced by SUBMITTED if the job has been submitted to the cluster, as opposed to executed locally, on the server.</p>
 234 <p>COLLECTED file is empty and indicates that the job results were collected by the user. Due to asynchronous nature of the job it is possible that the job was started and finished, but the results has never been requested.</p>
 235 <p>RunnerConfig.xml file contains a complete description of the job and JABAWS can restart the job based on this description.</p>
 236 <p>procError.txt and procOutput.txt files contains the content of the standard out and standard error streams of the process.</p>
 237 <p>result.txt file contains the results.</p>
 238 <p>input.txt file contains input into the process.</p>
 239 <p>There are maybe other files depending on the nature of the job, but the one described above will be present in most cases. In this example, stat.log file stories the execution statistics generated by (clustal executable in this example) process.</p>
 240 <p>If you have deployed JABAWS WAR file or made changes to JABAWS configuration you may need to make a few changes to the Tomcat configuration to be able to see the content of the job directory. Please see the <a class="reference external" href="stats.html#configuring-jabaws-execution-statistics">Configuring JABAWS execution statistics</a> section for further details.</p>
 241 </div>
 242 <div class="section" id="configuring-jabaws-execution-statistics">
 243 <span id="stat-config"></span><h2>Configuring JABAWS execution statistics<a class="headerlink" href="#configuring-jabaws-execution-statistics" title="Permalink to this headline">¶</a></h2>
 244 <p>JABAWS execution statistics is a multi-component system. First is a crawler whose job is to collect and preprocess the statistics from the job temporary directories and record the collected statistics into the database. The second part of the system is a web application whose job is to visualise the statistics from the database.</p>
 245 <p>It is possible to enable/disable the statistics collector by changing the following properties in the <code class="docutils literal"><span class="pre">conf/Cluster.engine.properties</span></code> and <code class="docutils literal"><span class="pre">conf/Local.engine.properties</span></code> files.</p>
 246 <div class="highlight-bash"><div class="highlight"><pre><span></span><span class="c1"># Enable/disable cluster statistics collector true = enable, false = disable</span>
 247 cluster.stat.collector.enable<span class="o">=</span><span class="nb">false</span>
 248 <span class="c1"># Maximum amount of time the job is considered be running in hours. Optional defaults to 7 days (168h)</span>
 249 cluster.stat.maxruntime<span class="o">=</span><span class="m">24</span>
 250 </pre></div>
 251 </div>
 252 <div class="highlight-bash"><div class="highlight"><pre><span></span><span class="c1"># Enable/disable cluster statistics collector true = enable, false = disable</span>
 253 local.stat.collector.enable<span class="o">=</span><span class="nb">true</span>
 254 <span class="c1"># Maximum amount of time the job is considered to be running in hours. Optional defaults to 24 hours</span>
 255 local.stat.maxruntime<span class="o">=</span><span class="m">6</span>
 256 </pre></div>
 257 </div>
 258 <p>If the statistics collector is enabled then the crawler starts automatically soon after (10 minutes for local engine, and 60 minutes for cluster engine) the JABAWS web application and will be collecting the execution statistics every 24 hours after the start.</p>
 259 <p>The details of the job are only available if the job temporary directory is located within a JABAWS web application. If not, the system administrator can create a symbolic link pointing to the temporary job directories outside of a web application and configure the application server to allow navigation to the links. For the Tomcat application server the context configuration file should be created and copied to the <code class="docutils literal"><span class="pre">&lt;TOMCAT_ROOT&gt;/conf/Catalina/localhost</span></code> directory. The name of the file should be the same as the web application context name, for example <em>jabaws.xml</em> for jabaws. Where the <code class="docutils literal"><span class="pre">TOMCAT_ROOT</span></code> is the location of the Tomcat web application server. Here is an example of such a file:</p>
 260 <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
 261 <span class="nt">&lt;Context</span> <span class="na">antiResourceLocking=</span><span class="s">&quot;false&quot;</span> <span class="na">privileged=</span><span class="s">&quot;true&quot;</span> <span class="na">allowLinking=</span><span class="s">&quot;true&quot;</span><span class="nt">/&gt;</span>
 262 </pre></div>
 263 </div>
 264 <p>The key option here is this: <code class="docutils literal"><span class="pre">allowLinking=&quot;true&quot;</span></code>. Please also make sure that you have defined the user in role <em>admin</em> as described <a class="reference external" href="stats.htmll#configuring-a-privileged-access-for-tomcat-web-application-server">below</a>.</p>
 265 </div>
 266 <div class="section" id="configuring-a-privileged-access-for-tomcat-web-application-server">
 267 <span id="stat-tomcat-users"></span><h2>Configuring a privileged access for Tomcat web application server<a class="headerlink" href="#configuring-a-privileged-access-for-tomcat-web-application-server" title="Permalink to this headline">¶</a></h2>
 268 <p>Access to configuration files, detailed job execution statistics and job directories are allowed only for authenticated users in role <em>admin</em>.</p>
 269 <p>If you use Tomcat, then the simplest way to set up privileged access is to use a plain text configuration file <code class="docutils literal"><span class="pre">conf/tomcat-user.xml</span></code>. Here is an example of such configuration file defining user &#8220;peter&#8221; in role <em>admin</em>.</p>
 270 <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;tomcat-users&gt;</span>
 271 <span class="nt">&lt;role</span> <span class="na">rolename=</span><span class="s">&quot;admin&quot;</span><span class="nt">/&gt;</span>
 272 <span class="nt">&lt;user</span> <span class="na">username=</span><span class="s">&quot;peter&quot;</span> <span class="na">password=</span><span class="s">&quot;your password here &quot;</span> <span class="na">roles=</span><span class="s">&quot;admin&quot;</span><span class="nt">/&gt;</span>
 273 <span class="nt">&lt;/tomcat-users&gt;</span>
 274 </pre></div>
 275 </div>
 276 <p>For more information on users and roles please consult Apache-Tomcat help pages.</p>
 277 </div>
 278 </div>
 279
 280
 281            </div>
 282            <div class="articleComments">
 283
 284            </div>
 285           </div>
 286           <footer>
 287
 288     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 289
 290         <a href="citations.html" class="btn btn-neutral float-right" title="Citations" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
 291
 292
 293         <a href="develop.html" class="btn btn-neutral" title="For Developers" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
 294
 295     </div>
 296
 297
 298   <hr/>
 299
 300   <div role="contentinfo">
 301     <p><a href="../">JABAWS 2.2</a>
 302         &copy; Copyright 2017, Peter Troshin, Alexander Sherstnev, Jim Procter, Alexey Drozdetskiy, Daniel Barton, Suzanne Duce, Fábio Madeira and Geoff Barton.
 303
 304     </p>
 305   </div>
 306   Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
 307
 308 </footer>
 309         </div>
 310       </div>
 311
 312     </section>
 313
 314   </div>
 315
 316
 317
 318
 319
 320     <script type="text/javascript">
 321         var DOCUMENTATION_OPTIONS = {
 322             URL_ROOT:'./',
 323             VERSION:'2.2',
 324             LANGUAGE:'None',
 325             COLLAPSE_INDEX:false,
 326             FILE_SUFFIX:'.html',
 327             HAS_SOURCE:  true,
 328             SOURCELINK_SUFFIX: '.txt'
 329         };
 330     </script>
 331       <script type="text/javascript" src="_static/jquery.js"></script>
 332       <script type="text/javascript" src="_static/underscore.js"></script>
 333       <script type="text/javascript" src="_static/doctools.js"></script>
 334
 335
 336
 337
 338
 339     <script type="text/javascript" src="_static/js/theme.js"></script>
 340
 341
 342
 343
 344   <script type="text/javascript">
 345       jQuery(function () {
 346           SphinxRtdTheme.StickyNav.enable();
 347       });
 348   </script>
 349
 350
 351 </body>
 352 </html>