123 lines
4 KiB
Markdown
123 lines
4 KiB
Markdown
> **AI-Generated Content Warning:** This project was developed with the assistance of generative AI (Claude by Anthropic). Code, documentation, and design decisions may reflect AI-generated output and should be reviewed accordingly before use in production environments.
|
|
|
|
---
|
|
|
|
# // NXSTATS //
|
|
|
|
A fast nginx log parser that generates themeable HTML reports with charts, searchable tables, and optional GeoIP2 hit maps.
|
|
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- Parses nginx **access** and **error** logs, including gzip-compressed rotated logs
|
|
- Generates a self-contained **single-file HTML report** — no server required
|
|
- **Status code distribution** bar chart
|
|
- **Top paths** and **requests-per-hour** charts (Chart.js)
|
|
- Searchable, filterable **access log table** with status badges
|
|
- Optional **GeoIP2 world map** (Leaflet.js) when a MaxMind `.mmdb` is supplied
|
|
- **Split-by-day** mode writes one report per calendar day plus a summary index page
|
|
- Three built-in **themes** — `cyberpunk` (neon dark), `purplerain` (modern purple dark), `cactus` (pastel green light)
|
|
- Zero runtime dependencies — the binary is statically compiled Go
|
|
|
|
## Installation
|
|
|
|
### Build from source
|
|
|
|
Requires Go 1.21+.
|
|
|
|
```bash
|
|
git clone https://github.com/mr0xb/nxstats.git
|
|
cd nxstats
|
|
go build -o nxstats .
|
|
```
|
|
|
|
### Pre-built binary
|
|
|
|
Download the latest release binary from the [releases page](../../releases) and place it somewhere on your `$PATH`.
|
|
|
|
## Usage
|
|
|
|
```
|
|
nxstats [flags]
|
|
```
|
|
|
|
| Flag | Short | Default | Description |
|
|
|---|---|---|---|
|
|
| `--dir` | `-d` | `/var/log/nginx` | Directory to scan for nginx logs |
|
|
| `--output` | `-o` | `report.html` | Output HTML file path |
|
|
| `--access-log` | `-a` | | Specific access log file (skips dir scan) |
|
|
| `--error-log` | `-e` | | Specific error log file (skips dir scan) |
|
|
| `--geoip` | | | Path to MaxMind `GeoLite2-City.mmdb` (enables map) |
|
|
| `--no-gzip` | | `false` | Skip `.gz` compressed rotated logs |
|
|
| `--split-by-day` | | `false` | Write one HTML report per calendar day plus index |
|
|
| `--theme` | | `cyberpunk` | Report visual theme: `cyberpunk`, `purplerain`, `cactus` |
|
|
| `--map-api-key` | | | CARTO basemap API key, appended to tile URLs as `?key=` (env: `NXSTATS_MAP_API_KEY`) |
|
|
|
|
### Examples
|
|
|
|
**Quick report from the default nginx log directory:**
|
|
```bash
|
|
nxstats -o report.html
|
|
```
|
|
|
|
**Specific log files:**
|
|
```bash
|
|
nxstats -a /var/log/nginx/access.log -e /var/log/nginx/error.log -o report.html
|
|
```
|
|
|
|
**With GeoIP2 map enabled:**
|
|
```bash
|
|
nxstats --dir /var/log/nginx --geoip ./GeoLite2-City.mmdb -o report.html
|
|
```
|
|
|
|
**Split into per-day reports:**
|
|
```bash
|
|
nxstats --dir /var/log/nginx --split-by-day -o index.html
|
|
# Writes index.html + 2024-01-15.html, 2024-01-16.html, etc.
|
|
```
|
|
|
|
**With a CARTO basemap API key (required for map tiles):**
|
|
```bash
|
|
nxstats --geoip ./GeoLite2-City.mmdb --map-api-key XYZ -o report.html
|
|
# or: NXSTATS_MAP_API_KEY=XYZ nxstats --geoip ./GeoLite2-City.mmdb -o report.html
|
|
```
|
|
|
|
**With a different theme:**
|
|
```bash
|
|
nxstats --dir /var/log/nginx --theme purplerain -o report.html
|
|
```
|
|
|
|
## GeoIP2 Setup
|
|
|
|
The geographic distribution map requires a free MaxMind GeoLite2-City database.
|
|
|
|
1. Sign up at [maxmind.com](https://www.maxmind.com/en/geolite2/signup)
|
|
2. Download `GeoLite2-City.mmdb`
|
|
3. Pass the path via `--geoip ./GeoLite2-City.mmdb`
|
|
|
|
## Basemap API Key
|
|
|
|
The map's background tiles come from [CARTO](https://carto.com/), which now
|
|
requires an API key. Create one in the CARTO dashboard and pass it with
|
|
`--map-api-key` (or set `NXSTATS_MAP_API_KEY`); it is appended to the theme's
|
|
tile URL as `?key=...` in the generated report. Note that the key is embedded
|
|
in the HTML output, so treat generated reports as you would the key itself.
|
|
|
|
Without a key the map still renders, but tiles may come back blank.
|
|
|
|
## Log Format
|
|
|
|
nxstats expects the standard nginx combined log format for access logs:
|
|
|
|
```
|
|
$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"
|
|
```
|
|
|
|
Error logs use the standard nginx error log format.
|
|
|
|
## License
|
|
|
|
MIT
|