> **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.

![Dashboard overview](screenshot1.png)

![Access log table](screenshot2.png)

## 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` |

### 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 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`

## 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