Internal logger for Lean4Game.
It does two things:
- Collects usage statistics from open Lean4Game sessions.
- Checks which installed games are inactive and can eventually be cleaned up.
The Logger reads the Lean4Game sessions API and stores daily country/game statistics. The logic for aggregating statistics is located in the LocationMeter class. LocationMeter aims to provide estimates for daily playtime of games w.r.t. the players home country. This is done by aggregating information concerning anonymized player IPs as well as their currently accessed game session. This information is provided via API by Lean4Game.
The aggregated LocationMeter data is translated at a specified time by a job defined in the scheduler. Currently, translations are performed once a day, translating anonymized IPs into country abbreviations. The translations is performed by calling the ipinfo API for each persisted anonymized IP.
The translated location data is persisted under following path structure
./Location/logs/locations-2026-12-12.logA more accessible report of the persisted location data can be generated by the Reporter tool.
Lean4Game stores when a game was last seen, played, or uploaded. The Logger reads this data once per day and calculates the game status.
Stages:
active -> inactive -> deletion_due -> moved to .trash -> deleted
(trash entries are deleted after GAME_TRASH_RETENTION_DAYS).
The Logger writes reports to:
Activity/logs/activity-status.json
Activity/logs/cleanup-status.json
The Logger skips protected games, currently open games, invalid paths, symlinks, and missing folders.
Usage statistics are collected every ten minutes and represent information concerning maximal CPU and RAM usage as well as the maximal number of simultaneously active players over that time frame. The logic aggregating these measurements can be found in its dedicated class. These measurements are available to be retrieved by Lean4Game via API and saved locally via a dedicated job in the scheduler.
Persisted usage statistics can be found on the deployed system under:
./Usage/logs/usage-2026-12-12.logHardware statistics are generated by dedicated classes for both CPU and RAM. The underlying hardware measurements are retrieved by calling a locally hosted prometheus node-exporter instance.
The maximal RAM usage over the last ten minutes is computed in RAM by executing a single PromQL representing the following formula:
where both MemAvailable and MemTotal are values provided by node-exporter and the underlying Linux kernel.
Maximal CPU usage is calulated using a moving window approach. A window of 40 measurements is fixed, that contains the average percentage of idle-time over all the systems CPUs measured in 15 min intervals. The maximal CPU usage is therefore calculated by choosing the minimum of these measurements and subtracting it from one. More precisely, a single measurement of average CPU idleness for a point in time
The Usage meter integrates an instance of the LocationMeter class calling a dedicated method to retrieve the maximum number of players of the current aggregated measurement.
Logger exposes a read-only Prometheus endpoint for Lean4Game operational data.
It is separate from the local Flask API and binds to 127.0.0.1:8078 by default.
| Environment variable | Default | Purpose |
|---|---|---|
LOGGER_METRICS_HOST |
127.0.0.1 |
Interface for the Prometheus endpoint. |
LOGGER_METRICS_PORT |
8078 |
Port for the Prometheus endpoint. |
The endpoint exports aggregated data only: peak player/CPU/RAM measurements, job timing and failures, game lifecycle and cleanup outcomes, and country/game session observations. It never exports anonymized IP addresses.
For the existing Docker-based Prometheus deployment, configure a controlled container-to-host route and add Logger as a scrape target. Do not expose the metrics endpoint publicly. Grafana can then display the Logger metrics next to the existing node-exporter host-health dashboard.