1 <%--<?xml version="1.0" encoding="ISO-8859-1" ?>--%>
2 <%--<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>--%>
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" %>
10 <c:import url="../template_header.jsp" >
11 <c:param name="title">Documentation</c:param>
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>
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>
25 <div class="panel-body">
26 <!--<h4>JABAWS Server Virtual Appliance</h4>-->
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>
36 <!--<p class="justify">-->
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>
48 <div class="panel-body">
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.
59 If you are using JABAWS VA (Virtual Appliance) then the username is
60 <em2>jabaws</em2> and password is not defined,
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.
69 <p><img src="../static/img/usage_statistics_main.gif" alt="JABAWS usage statistics"
70 width="608" height="318" />
73 The table contains the number of jobs processed by JABAWS per month, for
74 the whole period when the statistics was collected.
76 <p>For each month the table contains the following information.</p>
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
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>
87 <p>The summary for each column is displayed in the last row of the table.</p>
89 <p class="text-right">
90 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
102 <div class="panel-body">
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.
110 <p class="text-right">
111 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
123 <div class="panel-body">
125 Detailed execution statistics for each month is available for
126 authenticated users only.
128 <p><img src="../static/img/usage_statistics_month.gif" alt="JABAWS one month usage statistics"
129 width="670" height="902" />
131 <p>Each table contains the number of jobs processed by JABAWS during the period of
132 time specified in the title:</p>
134 <li>The "All Jobs" table contains the summary of all jobs</li>
135 <li>"Local Jobs" table - contains the summary of the jobs calculated by the local engine</li>
136 <li>"Cluster Jobs" table - contains the summary of the jobs calculated by the cluster</li>
138 Each table contains the following information for each web service:
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>
145 <p class="text-right">
146 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
158 <div class="panel-body">
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
166 <p><img src="../static/img/usage_statistics_details.gif" alt="JABAWS - job list" width="917" height="198" /> </p>
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
183 <p class="text-right">
184 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
196 <div class="panel-body">
198 <img src="../static/img/usage_statistics_job_details.gif" alt="JABAWS- job details"
199 width="600" height="340" /></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.
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.
211 RunnerConfig.xml file contains a complete description of the job and JABAWS
212 can restart the job based on this description.
215 procError.txt and procOutput.txt files contains the content of the standard
216 out and standard error streams of the process.
218 <p>result.txt file contains the results. </p>
219 <p>input.txt file contains input into the process. </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)
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.
233 <p class="text-right">
234 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
246 <div class="panel-body">
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.
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.
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>
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.
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 <TOMCAT_ROOT>/conf/Catalina/localhost directory. The
280 name of the file should be the same as the web application context name,
281 for example "<em2>jabaws.xml</em2>" 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:
285 <pre><code class="xml"><?xml version="1.0" encoding="UTF-8"?>
286 <Context antiResourceLocking="false" privileged="true" allowLinking="true"/></code></pre>
288 The key option here is this:
289 <em2>allowLinking="true"</em2>.
290 Please also make sure that you have defined the user in role
291 "<em2>admin</em2>" as described
292 <a href="#conf_tomcat_user">below</a>.
294 <p class="text-right">
295 <a href="#">Back to top <i class="fa fa-arrow-up" aria-hidden="true"></i></a>
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>
308 <div class="panel-body">
310 Access to configuration files, detailed job execution statistics and job
311 directories are allowed only for authenticated users in role
312 "<em2>admin</em2>".
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 "<em2>peter</em2>" in role
319 "<em2>admin</em2>".
320 <pre><code class="xml"><tomcat-users>
321 <role rolename="admin"/>
322 <user username="peter" password="your password here " roles="admin"/>
323 </tomcat-users></code></pre>
324 <p>For more information on users and roles please consult Apache-Tomcat help pages.</p>
330 <jsp:include page="../template_footer.jsp" />