Control Application (Managing Applications)

Managing Applications, Flights, and Sessions in LogUI Server

The Applications component allows you to view and add applications, flights, and sessions to the LogUI server. If you are unsure what these are, please read the Wiki page that explains the basic concepts behind LogUI, and then come back to this page to learn how to use the application.

Applications

Applications currently stored in the database of your LogUI server instance can be listed by clicking on the Applications component icon, on the left of the screen. You will then see a screen similar to the one shown below.

If no applications are present on the system, you will be presented with a message instead of a table. Each row on the table provides the application's name, its unique identifier (a UUID), a timestamp of when it was created, and the number of flights it has associated with it. Click the row to view the flights associated with the application (if any).

Adding a New Application

Creating a new application on the LogUI server instance is easy. Click the Add New Application button at the top right of the page, or the Add New Application button from the component menu links on the left. You will then be presented with a simple form, as shown below.

As can be seen in the screenshot above, only a single field needs to be supplied — the name of the application. Enter it and click the Add New Application button to submit the form, or push ENTER. You will then be redirected back to the application listing page, where the new application should now be present.

Application names are unique. You cannot add two applications with the same name. This is not a requirement of the server's data model, and can be removed at a later date if required.

Flights

Just like viewing applications, flights can also be listed. To view flights for a specific application, simply click the row for the application in the application list view. You will then be presented with a page similar to the example screenshot presented below.

Just as with the application listing, you can add a new flight by clicking the Add New Flight button at the top right of the page.

For each row of the flight listing, you will see the following (from left to right).

• A flight status indicator (in green or red).
• The flight name.
• The domain at which the flight resides (with a link to it).
• The timestamp at which the flight was created in the LogUI database.
• A count of the number of sessions that have been recorded for the given flight.
• A link to view the authorisation token for the flight in question.
• A link to download any logged interaction data for the flight.

Adding a New Flight

You can create a new flight for the given application by clicking the Add New Flight button at the top right of the flight listing page. You will then be presented with a simple form.

In this form, two fields are required: the flight name; and the domain. The flight name is straightforward to understand — here, you must provide a name by which you can identify the flight you are creating. You can use the name of the experiment you are running, for example.

The domain field requires a greater description. Put simply, this field should be a well-formed domain that specifies the root of where your application resides. This could be formed of a hostname (e.g., server.tudelft.nl), or a portion of the complete URL including paths (e.g., server.tudelft.nl/app/). Whatever you choose, you need to make sure that this value will be shown in the address field of the browser when users interact with it. The URL is sent to the LogUI server when the initial server handshake occurs. This is checked against the URL you provide in this form. This check exists to ensure that malicious users cannot hijack the logger and inject random events into your interaction logs, messing everything up.

Are you running a page on your local computer without a web server (i.e., using file://)? If so, use http://localhost in the domain field. This has a special meaning in the LogUI server to accept requests from either localhost (your computer's web server), or from the file:// protocol.

If you are testing things out, or are not sure what the domain the final product will be hosted at, enter bypass into this field. This will ensure that all domain checks are skipped when the client using the given flight ID connects. Use this as a last resort; your system will be open to connections from malicious users!

Once you have provided both fields, click the Add New Flight button (or push ENTER). If successful, you will then be returned to the flights listing for the application in question. Your new flight should also be present.

Note that like application name, flight names are unique. This is not a constraint of the underlying data model; this constraint can be adjusted in the future if necessary.

Starting and Stopping Flights

On the flight listing page, you will notice the red and green circles on the left of each entry. These indicate whether the LogUI server instance is accepting new connections for the given flight. If green, LogUI server will accept new connections. If set to red, LogUI server will refuse any LogUI client that attempts to connect for the given flight. You can use this setting to prevent any additional interaction data being recorded (for example, if you are satisfied with the data you have collected).

Notice in the screenshot above, three out of five flights for the SearchX application are not accepting new connections. You can easily change the status of a flight by clicking on the indicator circle. It will then toggle to red if currently green, and vice versa.

If you switch a flight to disabled while users are connected to LogUI server, their connections will not be interrupted. Rather, this setting only affects new connections; not established connections.

The Authorisation Token

In order for a LogUI client to successfully connect to the LogUI server instance you are running, you will be required to provide an authorisation token for the client to send to the server. This encrypted string provides detailed information about the application and flight in question. If the provided information does not match what LogUI is expecting, it will reject the connection to the client.

Each flight has its own authorisation token. As this is encrypted, it may change each time you view the authorisation token page. This is normal behaviour; as long as you don't change the SECRET_KEY value in your deployment's environment file, authorisation will continue to work.

To view the authorisation token for a given flight, click the token symbol in the flight listing page for the flight concerned. You will then be presented with a page similar to the one below.

Note the random string inside the purple box. This is the token you need. We have provided a Copy Authorisation Token to Clipboard button to copy the token to your computer's clipboard. You can then paste this in the configuration object for the LogUI client you are using.

Sessions

You can view information on the individual sessions recorded for a given flight by clicking on the relevant flight's entry in the flight listings page. This will result in a page similar to the one presented in the screenshot below.

Note the option to view the authorisation token for the flight with the View Authorisation Token button at the top right, and the status indicator (in green) next to the flight's name at the top. Clicking this, like in the flight listings page, will allow or deny new connections to the flight in question.

The table below provides detailed information on data gathered about each individual session. From left to right, the information presented is listed below.

• The IP address of the client is shown.
• The unique identifier for the session (LogUI's internal identifier) is displayed underneath the IP address.
• The session start timestamp is provided, formatted to the server's local timezone.
• The session end timestamp is also provided, also formatted to the server's local timezone.
• A graphic determines whether the session was taking place on a traditional desktop/laptop device, or a tablet/smartphone.
• A further graphic illustrates the client's operating system.
• Another graphic denotes the client's web browser.
• The final indicator shows whether the session is complete (in green), or is in progress (in orange).

A session is said to be in progress when no end timestamp has been logged by the server. When an end timestamp is recorded, the session is then considered to be complete. For multi-page sessions, the end timestamp may be updated as the user continues to load new pages with the LogUI client.

Information pertaining to the client's setup is extracted from its agent string. This information may be incomplete or incorrect — we take no responsibility for the accuracy of this information.

Downloading Interaction Log Data

You can also download all recorded interaction log data for a given flight. This data is prepared in JSON format, meaning it is machine-readable out of the box, and ready for analysis scripts that you may have.

To download interaction log data, go to the flight listing page for the application in question. Find the flight from the listing that you want to download interaction data for, and click the Download button. This process may take a few seconds depending on how large the interaction log is, but your browser will then be sent a JSON log file, which it saves to your disk.

If you attempt to download interaction log data for a flight without any recorded sessions, you will be presented with an error message — as shown below.