docs/stats.rst

   1 Usage Statistics
   2 ================
   3
   4 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.
   5
   6 If you are using JABAWS VA (Virtual Appliance) then the username is *jabaws* and password is not defined, i.e. empty.
   7
   8 If you have deployed a JABAWS WAR file, then please see the `configuring privileged access`_ for Tomcat web application server section for further details.
   9
  10 .. image:: ../website/static/img/usage_statistics_main.gif
  11    :height: 318
  12    :width: 608
  13    :scale: 100 %
  14    :align: left
  15
  16 The table contains the number of jobs processed by JABAWS per month, for the whole period when the statistics was collected.
  17
  18 For each month the table contains the following information.
  19
  20 * 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
  21 * Total - the total number of jobs accepted by JABAWS
  22 * Incomplete - the number of jobs for which the result file was not found or was empty excluding cancelled
  23 * Cancelled - the number of jobs cancelled by the user
  24 * Abandoned - the number of jobs which result(s) were not collected
  25
  26 The summary for each column is displayed in the last row of the table.
  27
  28 ------------
  29
  30 .. _stat_details:
  31
  32 Detailed View
  33 -------------
  34
  35 Detailed execution statistics for each month is available for authenticated users only.
  36
  37 .. image:: ../website/static/img/usage_statistics_month.gif
  38    :height: 902
  39    :width: 670
  40    :scale: 100 %
  41    :align: left
  42
  43 Each table contains the number of jobs processed by JABAWS during the period of time specified in the title:
  44
  45 * The "All Jobs" table contains the summary of all jobs
  46 * "Local Jobs" table - contains the summary of the jobs calculated by the local engine
  47 * "Cluster Jobs" table - contains the summary of the jobs calculated by the cluster
  48
  49 Each table contains the following information for each web service:
  50
  51 * Total - the total number of jobs accepted by a particular JABA service
  52 * Incomplete - the number of jobs for which the result file was not found or was empty excluding cancelled
  53 * Cancelled - the number of jobs cancelled by the user
  54 * Abandoned - the number of jobs which result(s) were not collected
  55
  56 ------------
  57
  58 .. _stat_jobs:
  59
  60 Job List
  61 --------
  62
  63 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 `Configuring JABAWS execution statistics`_ section for further details.
  64
  65 .. image:: ../website/static/img/usage_statistics_details.gif
  66    :height: 198
  67    :width: 917
  68    :scale: 100 %
  69    :align: left
  70
  71 Columns:
  72
  73 * JobID - the JABAWS job id, unique for every job
  74 * Cluster JobID - cluster job id
  75 * InputSize - input size in bytes
  76 * ResultSize - result size in bytes
  77 * Runtime (s) - job's runtime in seconds
  78 * Start time (s)- job's start time and date
  79 * Finish time (s)- job's finish time and date
  80 * isCancelled - whether the job was cancelled
  81 * isCollected - whether the job was collected. False for the jobs that has been initiated but which results has never been retrieved
  82 * 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
  83
  84 ------------
  85
  86 .. _stat_dir_contents:
  87
  88 Job Directory Contents
  89 ----------------------
  90
  91 .. image:: ../website/static/img/usage_statistics_job_details.gif
  92    :height: 420
  93    :width: 716
  94    :scale: 90 %
  95    :align: left
  96
  97 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.
  98
  99 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.
 100
 101 RunnerConfig.xml file contains a complete description of the job and JABAWS can restart the job based on this description.
 102
 103 procError.txt and procOutput.txt files contains the content of the standard out and standard error streams of the process.
 104
 105 result.txt file contains the results.
 106
 107 input.txt file contains input into the process.
 108
 109 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.
 110
 111 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 `Configuring JABAWS execution statistics`_ section for further details.
 112
 113
 114 .. _stat_config:
 115
 116 Configuring JABAWS execution statistics
 117 ---------------------------------------
 118
 119 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.
 120
 121 It is possible to enable/disable the statistics collector by changing the following properties in the ``conf/Cluster.engine.properties`` and ``conf/Local.engine.properties`` files.
 122
 123 .. code-block:: bash
 124
 125     # Enable/disable cluster statistics collector true = enable, false = disable
 126     cluster.stat.collector.enable=false
 127     # Maximum amount of time the job is considered be running in hours. Optional defaults to 7 days (168h)
 128     cluster.stat.maxruntime=24
 129
 130 .. code-block:: bash
 131
 132     # Enable/disable cluster statistics collector true = enable, false = disable
 133     local.stat.collector.enable=true
 134     # Maximum amount of time the job is considered to be running in hours. Optional defaults to 24 hours
 135     local.stat.maxruntime=6
 136
 137 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.
 138
 139 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 ``<TOMCAT_ROOT>/conf/Catalina/localhost`` directory. The name of the file should be the same as the web application context name, for example *jabaws.xml* for jabaws. Where the ``TOMCAT_ROOT`` is the location of the Tomcat web application server. Here is an example of such a file:
 140
 141 .. code-block:: xml
 142
 143     <?xml version="1.0" encoding="UTF-8"?>
 144     <Context antiResourceLocking="false" privileged="true" allowLinking="true"/>
 145
 146 The key option here is this: ``allowLinking="true"``. Please also make sure that you have defined the user in role *admin* as described `below`_.
 147
 148
 149 .. _stat_tomcat_users:
 150
 151 Configuring a privileged access for Tomcat web application server
 152 -----------------------------------------------------------------
 153
 154 Access to configuration files, detailed job execution statistics and job directories are allowed only for authenticated users in role *admin*.
 155
 156 If you use Tomcat, then the simplest way to set up privileged access is to use a plain text configuration file ``conf/tomcat-user.xml``. Here is an example of such configuration file defining user "peter" in role *admin*.
 157
 158 .. code-block:: xml
 159
 160     <tomcat-users>
 161     <role rolename="admin"/>
 162     <user username="peter" password="your password here " roles="admin"/>
 163     </tomcat-users>
 164
 165 For more information on users and roles please consult Apache-Tomcat help pages.
 166
 167
 168 .. links
 169 .. _below: stats.htmll#configuring-a-privileged-access-for-tomcat-web-application-server
 170 .. _configuring privileged access: stats.htmll#configuring-a-privileged-access-for-tomcat-web-application-server
 171 .. _Configuring JABAWS execution statistics: stats.html#configuring-jabaws-execution-statistics