Nginx Live Traffic Monitor

A small Python/FastAPI dashboard for seeing live traffic through an Nginx reverse proxy. It follows one dedicated access log, aggregates requests into bounded one-second in-memory buckets, and streams telemetry to browsers over Server-Sent Events. There is no database or persistent application telemetry.

Requirements and installation

Python 3.10+ is required. From a checkout:

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Bulma and Chart.js are vendored under app/static/vendor, so the dashboard does not require browser access to a public CDN.

Nginx log format

Add the dedicated log (the application does not change Nginx configuration):

log_format traffic '$msec $host $request_method $status '
                   '$request_length $bytes_sent '
                   '$request_time $upstream_response_time';

access_log /var/log/nginx-traffic/traffic.log traffic;

The follower tolerates malformed lines, - upstream times, multiple upstream values, temporary disappearance, and rename/replacement rotation. It starts at the end of an existing file, like tail -F, so old log history is not mistaken for live traffic. The application keeps only configured rolling buckets (and bounded latency samples); totals are from application startup.

Running

python -m app.main

Open http://127.0.0.1:8080. Configuration is available through flags or environment variables:

Setting	Flag	Environment variable	Default
Traffic log	`--log-path`	`TRAFFIC_LOG_PATH`	`/var/log/nginx-traffic/traffic.log`
Listen address	`--host`	`LISTEN_ADDRESS`	`127.0.0.1`
Listen port	`--port`	`LISTEN_PORT`	`8080`
Retention seconds	`--retention`	`TELEMETRY_RETENTION`	`3600`

Example:

TRAFFIC_LOG_PATH=/var/log/nginx-traffic/traffic.log LISTEN_ADDRESS=0.0.0.0 LISTEN_PORT=8080 \
  python -m app.main --retention 3600

The visible window can be set to 1 minute, 5 minutes, 15 minutes, or 1 hour. A new browser receives enough current history to fill its selected graph window. Host names are discovered automatically and can be selected for breakout graphs. Theme selection (system, light, dark) is stored in browser local storage.

tmpfs and permissions

One possible tmpfs setup is:

sudo install -d -o nginx -g nginx -m 0750 /var/log/nginx-traffic
sudo mount -t tmpfs -o size=64M,mode=0750,uid=nginx,gid=nginx tmpfs /var/log/nginx-traffic

The service account needs search/read permission on the directory and read permission on traffic.log. If Nginx writes as another group, grant the monitor account group access or use an ACL, for example:

sudo setfacl -m u:nginx-monitor:rx /var/log/nginx-traffic
sudo setfacl -m u:nginx-monitor:r /var/log/nginx-traffic/traffic.log

systemd

Copy the included nginx-traffic-monitor.service to /etc/systemd/system/, adjust WorkingDirectory, virtualenv path, and the User/Group to match the installation, then:

sudo systemctl daemon-reload
sudo systemctl enable --now nginx-traffic-monitor
sudo systemctl status nginx-traffic-monitor

The service should run as an unprivileged account. Put a reverse proxy or firewall in front of it if it must be accessed beyond localhost; this utility intentionally has no authentication.

Development

Run the focused parser/aggregation tests with:

pytest -q

The server task follows the path by inode, drains currently available data from a renamed file, and reopens a replacement. A missing path is retried without busy polling. The publisher sends one compact snapshot per second to each SSE subscriber, and disconnecting clients are removed automatically.

3.7 KiB Raw Blame History