Logging¶

By default IDLive Face Server writes logs only to a standard output. If necessary you can mirror them to a file or send them to Logstash.

Logging to file¶

Set the LOGGING_FILE_NAME environment variable with a full path to a log file. Note that this is the path inside the container. You can use the directory /logs that has write access:

docker run --env LOGGING_FILE_NAME=/logs/server.log ...

To persist the logs after the container's restart put the directory with them into a volume:

docker run \
    --volume /var/log/idliveface:/logs \
    --env LOGGING_FILE_NAME=/logs/server.log \
    ...

This way the log file will available at the host as /var/log/idliveface/server.log.

Warning

You must create the host directory beforehand and allow write access for all users. Otherwise the Docker will create the directory with the root access only and IDLive Face Server won't be able to write logs to it.

Log files rotate when they reach 10 MB.

Logging to Logstash¶

Logs can be send over TCP to a running Logstash instance. To enable this feature set the LOGSTASH_HOST and LOGSTASH_PORT environment variables. If Logstash is configured to use TLS then additionally set the LOGSTASH_TLS environment variable.

Plain textWith TLS

docker run \
    --env LOGSTASH_HOST=10.0.0.1 \
    --env LOGSTASH_PORT=5959 \
    ...

docker run \
    --env LOGSTASH_HOST=10.0.0.1 \
    --env LOGSTASH_PORT=5959 \
    --env LOGSTASH_TLS=true \
    ...

Business Intelligence logs¶

Business Intelligence logs are enabled by default and saved to the /logs/bi.<hostname>.log file. The hostname part is the actual hostname of the container. As with normal logs you need to use a volume if you want to persist them. They also share the /logs directory but you can change the directory for BI logs if needed:

docker run --env IDFACE_SERVER_BI_LOGS_PATH=/bi ...

Setting the IDFACE_SERVER_BI_LOGS_PATH environment variable to an empty value will disable the BI log files:

docker run --env IDFACE_SERVER_BI_LOGS_PATH= ...

Additionally the BI logs can be sent to a default logging stream. This way they will function as the usual logs and can be configured as mentioned in the previous sections. To enable this set LOGGING_LEVEL_BI environment variable to INFO:

docker run --env LOGGING_LEVEL_BI=INFO ...

By default the size of BI logs is capped at 2 Gb. Once the maximum size is reached, some old logs will be deleted to make room for new ones. You can change the total logs' size with the IDFACE_SERVER_BI_LOGS_TOTAL_SIZE_CAP environment variable:

docker run --env IDFACE_SERVER_BI_LOGS_TOTAL_SIZE_CAP=1GB ...

Use MB or GB suffixes to set the size in megabytes or gigabytes.

Distributed Tracing ¶

IDLive Face Server supports Distributed Tracing using the Correlation ID passed in the request header. These enhancements provide powerful tools for tracing and logging requests throughout their lifecycle. Designed to improve monitoring, troubleshooting, and debugging processes, these features allow you to track requests across multiple systems and services.

IDLive Face Server utilizes two types of identifiers:

Correlation ID (correlation-id) - a unique identifier that should be included in each request to the server.
Session ID (session-id) - an identifier used to group multiple requests (each with its own Correlation ID) for the same user. This is particularly useful if the first requests fail for some reason. Multiple requests can share the same Session ID, so it is not unique to each request.

The server's logging framework includes both the Correlation ID and Session ID in log entries.

To make a request using cURL with the necessary headers, use the following command:

curl "http://127.0.0.1:8080/check_liveness" --form image=@/path/to/image/image.jpg -H 'session-id:12345678' -H 'correlation-id:87654321'

In this case, the log output may look like:

2024-03-25T20:40:23.299Z  INFO 2398704 --- [idliveface-server] [nio-8080-exec-1] [12345678][87654321] n.i.idliveface.server.V1ApiController    : Liveness check performed for abb82a85-87fa-4bae-aa82-a1f32d3ef6cd-00 file(s), iris pipeline, UNKNOWN os, REGULAR calibration with CheckLivenessResponse{score=1.815922, quality=0.999452, probability=0.860076} in 795 ms

The format of IDs in logs can be customized using the environment variable LOGGING_PATTERN_CORRELATION. For example:

docker run --env LOGGING_PATTERN_CORRELATION='[session-id=%X{session-id:-}, correlation-id=%X{correlation-id:-}] '  ...

In this case, the log output may look like:

2024-03-25T20:43:53.783Z  INFO 2404914 --- [idliveface-server] [nio-8080-exec-1] [session-id=12345678, correlation-id=87654321] n.i.idliveface.server.V1ApiController    : Liveness check performed for f764dcae-cc22-44cd-a3e4-f0be45155e65-00 file(s), iris pipeline, UNKNOWN os, REGULAR calibration with CheckLivenessResponse{score=1.815922, quality=0.999452, probability=0.860076} in 743 ms