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

To monitor an application, it must be equipped with an interceptor for events. This interceptor must transform the events into JSON messages as the one shown above and sent these messages to the port opened by the monitor. The monitor will then extract the messages and store the data in the log files.

The log files are separated in the log directory by the application id as well as by the client id. This means, the interceptor must ensure, that application and client id are as unique as required by further analysis. A client id may for example be unique for a certain installation of an application on a certain host. But it may also be unique for a certain user. This depends on which information about the user is available at runtime of the monitored application.

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)