[[TracNav(TOC|nocollapse)]]

= Monitor for HTML- and JavaScript-based Web Applications =

To analyse the usage of an HTML- and JavaScript-based web application with AutoQUEST, the usage of the website must be recorded. For this, AutoQUEST provides a so called monitor. The monitor is a standalone application for Java on Linux based on a Webserver that does both
 * provide a JavaScript integrated into a website to record the user actions
 * receive the recorded user actions from the JavaScript via AJAX and store them into local logfiles

== Installation of the Monitor ==

To install the monitor, it must first be downloaded. As AutoQUEST is under continuous development, it is always good to download the latest tested version from our continous integration environment which is available [https://trex.informatik.uni-goettingen.de/hudson/job/autoquest-htmlmonitor/lastSuccessfulBuild/de.ugoe.cs.autoquest$autoquest-htmlmonitor/ here]. There, just download the autoquest-htmlmonitor-version-bin.tar.gz.

Afterwards, the tar-file needs to be extracted to a preferred location. The resulting folder structure will look as follows:
 * autoquest-htmlmonitor-version
  * data
   * robots
    * robotsfilter.txt
  * lib
    * <some libraries (jar-files)>
  * autoquest-htmlmonitor-version.jar
  * run.sh
  * stop.sh
  * isRunning.sh

After the first start of the monitor, a further folder called log will be added. In this folder, the logfiles will be stored. The log directory can be changed using start parameters for the monitor (see next Section).


== Starting and Stopping the Monitor ==

To start the monitor, change into the installation directory and type {{{./run.sh}}}. The monitor will run in the background. To check, if the monitor is running, type {{{./isRunning.sh}}}. To stop the monitor, you can type {{{./stop.sh}}}. Per default, the monitor logs the recorded actions into a directory named {{{log}}}. To change this directory, you can start the monitor with a parameter denoting the path to the intended log directory. For example, to log into the directory {{{myLogDir}}}, the monitor must be started with the command {{{./run.sh myLogDir}}}.

When started, the monitor listens on port 8090 per default. To check, if the monitor is listening on the port, you can type {{{wget localhost:8090/script/autoquest-htmlmonitor.js}}}. As a result, the monitor should respond with the JavaScript for recording user actions. To change the port, you can provide a different port as the second parameter to the {{{run.sh}}} command. For example, to log into the directory {{{log}}} and to listen on port 8099 the monitor must be started using the command {{{./run.sh log 8099}}}. While running, the monitor logs messages about its status to a file called {{{console.log}}} which is also stored in the log directory.


== Monitoring Web Applications ==

To monitor web applications, the JavaScript provided by the monitor needs to be integrated into each page of the web application. For example, if a monitor is running on host {{{host}}} and port {{{1234}}}, then each page of the web application must include the following JavaScript
{{{
  <script type="text/javascript" src="http://host:1234/script/autoquest-htmlmonitor.js"></script>
}}}

In this simple setup, recorded user data will be sent unencrypted from the users browser to the server. Hence, the setup should be changed to support encryption. For this, several options exist. A good solution is to have a further Apache webserver which listens on an encrypted port and forwards any request machine internally to the unencrypted port of the monitor. In this case, the integration of the script into the pages of the monitored website must be adapted to match the changed setup.

After the JavaScript is integrated into the web pages, the browser of the user will execute it on each loading of the pages. The script will ensure to register for any user action. If 10 actions were recorded, if a timeout occurs, or if the user leaves the page, all recorded user actions will be sent to the monitor for storing them into the log files.

Log files are separated in the log directory by the URL of the monitored web application as well as by a unique id of the client. Please note, that a client here is a specific installation of a specific browser on a specific machine. If the installation changes, the client id may change. If several users use the same installed browser, they are considered as one user. To check if the monitor correctly records user actions, you can check if a specific log file is created in the log directory. Furthermore, you can check the {{{console.log}}} for respective messages, e.g. the following one:
{{{
  handled message of 12345 (www.mywebapp.de; 5 events)
}}}