ngxstat

ngxstat is a lightweight log analytics toolkit for Nginx. It imports access logs into an SQLite database and renders static dashboards so you can explore per-domain metrics without running a heavy backend service.

Requirements

• Python 3.10+
• Access to the Nginx log files (default: /var/log/nginx)

The helper scripts create a virtual environment on first run, but you can also set one up manually:

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

Importing Logs

Run the importer to ingest new log entries into database/ngxstat.db:

./run-import.sh

Rotated logs are processed in order and only entries newer than the last imported timestamp are added.

Generating Reports

To build the HTML dashboard and JSON data files use run-reports.sh which runs all intervals in one go:

./run-reports.sh

The script calls scripts/generate_reports.py internally to create hourly, daily, weekly and monthly reports, then writes analysis JSON files used by the "Analysis" tab. Per-domain reports are written under output/domains/<domain> alongside the aggregate data. Open output/index.html in a browser to view the dashboard.

If you prefer to run individual commands you can invoke the generator directly:

python scripts/generate_reports.py hourly
python scripts/generate_reports.py daily --all-domains

Analysis Helpers

run-analysis.sh executes additional utilities that examine the database for missing domains, caching opportunities and potential threats. The JSON output is saved under output/analysis and appears in the "Analysis" tab. The run-reports.sh script also generates these JSON files as part of the build.

UX Controls

The dashboard defaults to a 7‑day window for time series. Your view preferences persist locally in the browser under the ngxstat-state-v2 key. Use the "Reset view" button to clear saved state and restore defaults.

./run-analysis.sh

Serving the Reports

The generated files are static. You can serve them with a simple Nginx block:

server {
    listen 80;
    server_name example.com;
    root /path/to/ngxstat/output;

    location / {
        try_files $uri $uri/ =404;
    }
}

Restrict access if the reports should not be public.

Running Tests

Install the development dependencies and execute the suite with pytest:

pip install -r requirements.txt
pytest -q

All tests must pass before submitting changes.

Acknowledgements

ngxstat uses the following third‑party resources:

• Chart.js for charts
• DataTables and jQuery for table views
• Bulma CSS for styling
• Icons from Free CC0 Icons by Jon Hicks (CC0 / MIT)
• Typer for the command-line interface
• Jinja2 for templating

The project is licensed under the GPLv3. Icon assets remain in the public domain via the CC0 license.