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

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:

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:

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.