gpii-universal/gpii/node_modules/eventLog/README.md

Cross platform, core components of the GPII personalization infrastructure.

# GPII Event Log

Produces logs that can be read by a backend server for analysis and auditing. The log is in JSON format, and is sent
to an external log server via tcp.

Rather than transforming the fluid.log output, this module was produced so the debug log is still usable by humans and
it serves as a way of opting-in to sending only useful (and non-private) information.

## Log Destination

GPII sends the log data to the Filebeat service on the localhost, via tcp. This can be overridden by setting the
`logDestination` option of the `gpii.eventLog` grade, or the environment variable `GPII_EVENT_LOG`, to either the path
to a file or a tcp URI (`tcp://127.0.0.1:51481`).

If GPII is unable to connect to the log server, then the log data is buffered in memory until the connection can be
made.

### Filebeat

Filebeat is usually automatically installed with GPII. The Filebeat configuration and installer module is in
[github.com/stegru/gpii-metrics/.../filebeat-installer](https://github.com/stegru/gpii-metrics/tree/master/filebeat-installer)

## Logged Events

This module records GPII related events, listed below. For the additional events, related to the OS, see
[gpii-windows/gpii/node_modules/windowsMetrics/README.md](https://github.com/GPII/windows/blob/master/gpii/node_modules/windowsMetrics/README.md).

All logged events contain the following data:

```json5
{
    "module": "gpii", // The area of GPII that caused this event
    "event": "start", // The event name
    "data": {
        // Additional fields specific to the event
    },
    "installID": "hK/Dvo1GG8", // Unique identifier of the installation.
    "sequence": 60689584, // Incrementing number, unique per installation.
    "timestamp": "2018-10-31T06:45:21.971-07:00", // When the event occurred
    "version": "0.4.0", // The version of this module (or the windows metrics, if higher).

    // The following are optional, depending on the current state:
    "sessionID": "4acr8sks-4069", // unique session identifier
    "subSessionID": "4acr8sks-4069-5", // unique sub-session identifier
    "logon": "in", // "in" or "out" if currently logging in/out - "in-after"/"out-after" 10 seconds after log in/out.
                   // for any other time, this field does not exist.
    "gpiiKey": "d90eda4e-d1cd-415b-9605-dd9ce8be6359", // gpiiKey currently in use,
    // from the UI:
    "app": "active", // The active window belongs to Morphic.
    "focus": "openUSB", // The button that currently has focus (combine with "app" to determine if it has system focus)
    "hover": "launch-documorph", // The button that the mouse is currently hovering over.
    "widget-hover": "openUSB", // The QSS pop-up that the mouse is over.
    "field-hover": "ejectUsbButton", // The field within the pop-up that the mouse is over.
    "field-focus": "regular-contrast", // The field within the pop-up that has key focus.
}
```

### Start and stop

When GPII starts

```json5
{
      "module": "gpii",
      "event": "start",
}
```

```json5
{
      "module": "gpii",
      "event": "stop",
}
```

### Session start and end

When a user session starts.

```json5
{
    "module": "lifecycle",
    "event": "SessionStart"
}
```

```json5
{
    "module": "lifecycle",
    "event": "SessionStop",
    "data": {
        "duration": 481 // number of seconds the session lasted.
    }
}
```

### Solutions

When a solution has been applied or failed.

```json5
{
    "module": "metrics",
    "event": "solution-applied",
    "data": {
        "solutionID": "com.microsoft.windows.screenDPI"
    }
}
```

```json5
{
    "module": "metrics",
    "event": "solution-failed",
    "data": {
        "solutionID": "com.microsoft.windows.screenResolution"
    }
}
```

### Preference

A preference has been set

```json5
{
    "module": "metrics",
    "event": "preference",
    "data": {
        "name": "http://registry.gpii.net/common/highContrastTheme",
        "value": "black-white"
    }
}
```

### Errors

Two types of errors are recorded - those raised by `fluid.fail`, and uncaught exceptions.

```json5
{
    "event": "Error.Fail",
    "module": "GPII",
    "data": {
        "error": {
            "message": "Received an invalid screen resolution:  [object Object]",
            "stack": "..."
        }
    }
}
```

```json5
{
    "event": "Error.Exception",
    "module": "GPII",
    "data": {
        "error": {
            "message": "Cannot read property 'inferredConfiguration' of undefined",
            "stack": "..."
        }
    }
}
```