Monitor for Generic Events

To analyse the usage of applications with AutoQUEST, their usage must first be recorded. For this, an application must be instrumented to intercept the events caused by the actions of the users. These events must then be stored somewhere. For this, the Generic Event Monitor can be used. The monitor is a standalone application for Java on Linux based on a Webserver. Via the web server, it receives the recorded events in a JSON format via an HTTP post. An example for a JSON message with two recorded event is the following:

{
  "message": {
    "clientInfos": {
      "clientId":"clientId",
      "appId":"appId",
    }," +
    "targetStructure": [{
      "targetId":"target1",
      "param1":"value1",
      "param3":"value3",
      "param2":"value2",
      "children":
      [ {
          "targetId":"target2",
          "index":"0",
        },
        {
          "targetId":"target3",
          "htmlId":"gsr",
        }
      ]
    }],
    "events":
    [ {
        "time":"12345",
        "targetId":"target2",
        "type":"gaze",
        "xcoordinate": "194",
        "ycoordinate": "12"
      },
      {
        "time":"12346",
        "targetId":"target3",
        "type":"use",
        "param1": "value1",
        "param2": "value2"
      }"
    ]
  }
}

The message starts with some client information. This is required to distinguish received messages regarding their sender (client id) and the application for which the events were recorded (app id). The monitor uses this information for structuring the locally stored log files into corresponding sub folders. The next part is the target structure. It provides information about relevant event targets. The targets can be substructured hierarchically in any depth. In the example, the event target with id "target1" has three parameters and two child targets. The target ids need to be unique within a message. Finally, the message contains the events. Each event has a time stamp, a reference to the event target for which it was recorded, and a type. In addition, an event can be refined using freely choosable parameters in form of key value pairs.

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 ​here. There, just download the autoquest-generic-event-monitor-version-bin.tar.gz. The current versions of the monitor require an installed Java Runtime Environment version 1.8 or higher.

Afterwards, the tar-file needs to be extracted to a preferred location. The resulting folder structure will look as follows:

• autoquest-generic-event-monitor-version
  • lib
    • <some libraries (jar-files)>
  • autoquest-generic-event-monitor-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). The sub directories of the log directory will be created depending on the application and client ids provided in the received JSON message (see above).

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 Applications

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 for app BlaBliBlup (5 events)