105 lines
2.7 KiB
Markdown
105 lines
2.7 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```bash
|
||
./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:
|
||
|
||
```bash
|
||
./run-reports.sh
|
||
```
|
||
|
||
The script calls `scripts/generate_reports.py` internally to create hourly,
|
||
daily, weekly and monthly reports. 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:
|
||
|
||
```bash
|
||
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 of the
|
||
dashboard.
|
||
|
||
```bash
|
||
./run-analysis.sh
|
||
```
|
||
|
||
## Serving the Reports
|
||
|
||
The generated files are static. You can serve them with a simple Nginx block:
|
||
|
||
```nginx
|
||
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`:
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
pytest -q
|
||
```
|
||
|
||
All tests must pass before submitting changes.
|
||
|
||
## Acknowledgements
|
||
|
||
ngxstat uses the following third‑party resources:
|
||
|
||
* [Chart.js](https://www.chartjs.org/) for charts
|
||
* [DataTables](https://datatables.net/) and [jQuery](https://jquery.com/) for table views
|
||
* [Bulma CSS](https://bulma.io/) for styling
|
||
* Icons from [Free CC0 Icons](https://cc0-icons.jonh.eu/) by Jon Hicks (CC0 / MIT)
|
||
* [Typer](https://typer.tiangolo.com/) for the command-line interface
|
||
* [Jinja2](https://palletsprojects.com/p/jinja/) for templating
|
||
|
||
The project is licensed under the GPLv3. Icon assets remain in the public domain
|
||
via the CC0 license.
|