gpii-windows/gpii/node_modules/windowsMetrics/README.md

Components of the GPII personalization infrastructure for use on Microsoft's "Windows" ™

# GPII Windows Metrics

This modules provides the ability to capture certain ways in which the system is being used. The data is written to a
log file and uploaded to a log server via an external process, Filebeat.

The main purpose is to be able to record the impact that GPII has on how the user uses their computer. See the
*Automatic Data Collected and Rationale* document for further information.

No personally identifiable data is captured.

The following metrics are captured:

## System Metrics

### GPII Versions

The version of the gpii-windows, gpii-universal, gpii-app, and windowsMetrics modules are logged on startup.

Example:
```json5
{
    "module": "metrics",
    "event": "version",
    "level": "INFO",
    "data": {
        "windowsMetrics": "0.3.0",
        "gpii-app": "0.3.0-dev.20180315T174453Z.02de41c",
        "gpii-windows": "0.3.0-dev.20180315T174453Z.02de41c",
        "gpii-universal": "0.3.0-dev.20180905T001251Z.a9b24952"
    }
}
```

### System Information

On start up, CPU, memory, display and Windows version is recorded.

Example:
```json5
{
    "module": "metrics",
    "event": "system-info",
    "level": "INFO",
    "data": {
        "cpu": "Intel(R) Core(TM) i7-4770 CPU @ 3.40GHz",
        "cores": 2,
        "memory": "2.0",
        "resolution": "1280x951",
        "scale": "1.25",
        "osRelease": "10.0.17134",
        "osEdition": "Windows 10 Enterprise Evaluation",
        "osBits": "64",
        "systemMfr": "innotek GmbH",
        "systemName": "VirtualBox"
    }
}
```

### Live configuration

When various settings change, either by Morphic or something else such as control panel.

Resolution:
```json5
{
    "module": "metrics",
    "event": "config.resolution",
    "level": "INFO",
    "data": {
        "wp": 24,
        "lp": 50332672,
        "msg": "WM_DISPLAYCHANGE",
        "width": 1024,
        "height": 768,
        "bpp": 24 // omitted if 32
    }
}
```

Something changed via SystemParametersInfo:
```json5
{
    "module": "metrics",
    "event": "config.spi",
    "level": "INFO",
    "data": {
        "wp": 59,
        "lp": 2,
        "msg": "WM_SETTINGCHANGE",
        "action": "SPI_SETSTICKYKEYS"
    }
}
```

Other settings:
```json5
{
    "module": "metrics",
    "event": "config",
    "level": "INFO",
    "data": {
        "wp": 1,
        "lp": 2,
        "msg": "WM_SYSCOLORCHANGE"
    }
}
```

### Application launch

An application launch is logged when a window is first activated.

Example:
```json5
{
    "module": "metrics",
    "event": "app-launch",
    "level": "INFO",
    "data": {
        // Standard environment variables are used in place of the real path, where possible.
        "exe": "%SystemRoot%\\notepad.exe",
        "pid": 480,
        "windowClass": "Notepad"
    }
}
```

### Application close

When the last Window is closed, and the process terminates.

Example:
```json5
{
    "module": "metrics",
    "event": "app-close",
    "level": "INFO",
    "data": {
        "exe": "%SystemRoot%\\notepad.exe",
        "pid": 480,
        "windowClass": "Notepad"
    }
}
```

### Window Activation

When a window has been activated. The `window` field identifies the window, to determine if a different window of the
same process has been activated. 

Example:
```json5
{
    "module": "metrics",
    "event": "app-active",
    "level": "INFO",
    "data": {
        "exe": "%SystemRoot%\\notepad.exe",
        "window": "41k-494w",
        "windowClass": "Notepad"
    }
}
```

### Inactivity

When the user is not using the computer.

Example:
```json5
{
    "module": "metrics",
    "event": "inactive-begin",
    "level": "INFO"
}
```

And when the usage is resumed.

```json5
{
    "module": "metrics",
    "event": "inactive-stop",
    "level": "INFO",
    "data": {
        "duration": 42
    }
}
```

## Input metrics

### Typing

When a key is pressed, any modifier keys (`CTRL`, `ALT`, or `SHIFT`) and number of milliseconds since the last key is
logged.

The value of printable keys are not recorded.

For Shift + A:
```json5
{
    "module": "metrics",
    "event": "key-time",
    "level": "INFO",
    "data": {
        "keyTime": 260,
        "modifierKeys": [
            "SHIFT"
        ]
    }
}
```

Alt + F4:
```json5
{
    "module": "metrics",
    "event": "key-time",
    "level": "INFO",
    "data": {
        "key": "F4",
        "keyTime": 109,
        "modifierKeys": [
            "ALT"
        ]
    }
}
```

Also logged is the typing rate and corrections of a typing session.

```json5
{
    "module": "metrics",
    "event": "typing-session",
    "level": "INFO",
    "data": {
        "duration": 60000,
        "count": 3,
        "corrections": 0,
        "rate": 3
    }
}
```

### Mouse usage

Mouse clicks and wheel scrolls are recorded, along with the total distance travelled between clicks.

The location of the click is not recorded.

```json5
{
    "module": "metrics",
    "event": "mouse",
    "level": "INFO",
    "data": {
        "button": 1,
        "distance": 482
    }
}
```

For mouse wheels, the number of 'ticks' in the sample is captured (the scroll speed).

```json5
{
    "module": "metrics",
    "event": "mouse",
    "level": "INFO",
    "data": {
        "wheel": -1,
        "modifierKeys": [
            "CONTROL"
        ]
    }
}
```