# Device Metrics Server

## Overview

The device metrics server is a standalone server used to store and retrieve device metrics collected during face liveness evaluations. Face liveness servers connect to it to persist metrics centrally rather than writing them to a local log file.

This server is intended for deployments that run **multiple face liveness server instances**. In such environments, each face liveness server connects to a single shared device metrics server so that device data is aggregated in one place rather than spread across per-instance log files.

For single-server deployments, the local device metrics log (`--device-metrics-log-path`) is sufficient and no device metrics server is needed.

## Architecture

```
+-------------------------+
|  Face Liveness Server 1 │--+
+-------------------------+  |    +-----------------------+
                             |--->| Device Metrics Server |
+-------------------------+  |    +-----------------------+
|  Face Liveness Server 2 |--+
+-------------------------+  |
                             |
+-------------------------+  |
|  Face Liveness Server N |--+
+-------------------------+
```

A single device metrics server handles requests from all face liveness server instances in the deployment.

## When to Use

| Deployment type                | Recommended approach                           |
| ------------------------------ | ---------------------------------------------- |
| Single face liveness server    | Local log file (`--device-metrics-log-path`)   |
| Multiple face liveness servers | Device metrics server (`--device-metrics-url`) |

When `--device-metrics-url` is configured, each face liveness server sends device metrics to the device metrics server instead of writing to its local log. The local log and the remote server are mutually exclusive — configure one or the other. To disable the device metrics use, set `--device-metrics-log-path` to the empty string and do not set `--device-metrics-url`.

## Requirements

Java JRE version 17

## Starting the server

```bash
mkdir data
java -jar aw_device_metrics_server.jar
```

The server starts on port **9087** and creates `device_metrics.db` in the `data` directory.

To check if the server is running, you can hit the `/version` endpoint. For example:

```
curl http://localhost:9087/devicemetrics/version
```


### Changing the port

The example shows how the port can be changed when starting the server:

```bash
java -jar aw_device_metrics_server.jar --server.port=9090
```

Or it can be changed using environment variables for Linux:

```
export SERVER_PORT=9090
java -jar aw_device_metrics_server.jar
```

Or Windows:

```
set SERVER_PORT=9090
java -jar aw_device_metrics_server.jar
```

### Changing the location of stored data

The following option can be used to change the directory of the stored data:

```
--spring.datasource.url=jdbc:sqlite:/custom/path/to/database.db
```

Note that any parent directories must exist before starting the server.


### Setting TLS Keys

The following example shows how to set TLS keys for the server:

```
java -jar aw_device_metrics_server.jar \
  --spring.ssl.bundle.pem.mybundle.keystore.certificate=file:/path/to/cert.pem \
  --spring.ssl.bundle.pem.mybundle.keystore.private-key=file:/path/to/key.pem \
  --server.ssl.bundle=mybundle
```

If the private key is password protected, you should also pass `--spring.ssl.bundle.pem.mybundle.keystore.private-key-password=your_password`.

These values can also be set with environment variables. For example:

```
EXPORT SPRING_SSL_BUNDLE_PEM_MYBUNDLE_KEYSTORE_certificate=file:/path/to/cert.pem \
EXPORT SPRING_SSL_BUNDLE_PEM_MYBUNDLE_KEYSTORE_PRIVATE_KEY=file:/path/to/key.pem \
EXPORT SERVER_SSL_BUNDLE=mybundle
EXPORT SPRING_SSL_BUNDLE.PEM.MYBUNDLE.KEYSTORE.PRIVATE_KEY_PASSWORD=your_password

java -jar aw_device_metrics_server.jar
```

## Face Liveness Configuration

The face liveness server can be configured to use the device metrics server in one the of the following ways:

This option can also be set on the command line or via environment variable:

**Command Line Option:**

: `--device-metrics-url`

**Configuration File Parameter:**

: `device-metrics-url`

**Environment Variable:**

: `KNOMI_FACE_LIVENESS_DEVICE_METRICS_URL`

The following is an example of setting the URL in the configuration file:

```{code-block} ini
device-metrics-url=http://localhost:9087/devicemetrics
```

When one of these options is set, local log writing will be disabled.

To completely disable device metrics use, do not set the metrics URL and set the device metrics log path to an empty string.