A Lightweight Nginx Log Analyzer That Finally Works

Overview

Lightweight Nginx log analysis panel that provides real‑time PV/UV statistics, IP geolocation, client/browser parsing, multi‑site support, and custom log format handling.

Features

Real‑time PV/UV statistics

IP geolocation (ip2region for China, ip‑api for abroad)

Client and browser parsing

Multi‑site configuration

Custom log format support (direct log_format syntax or regex with named groups)

Tech Stack

Backend: Go + Gin; Frontend: Vue3 + Vite + PrimeVue; Database: SQLite (single file).

Deployment

Docker one‑liner

docker run -d --name nginxpulse \
  -p 8088:8088 \
  -p 8089:8089 \
  -e WEBSITES='[{"name":"Main","logPath":"/share/log/nginx/access.log","domains":["example.com"]}]' \
  -v /your/nginx/logs/access.log:/share/log/nginx/access.log:ro \
  -v $(pwd)/var/nginxpulse_data:/app/var/nginxpulse_data \
  magiccoders/nginxpulse:latest

Replace /your/nginx/logs/access.log with the actual log file path.

Docker Compose

version: "3.8"
services:
  nginxpulse:
    image: magiccoders/nginxpulse:latest
    container_name: nginxpulse
    ports:
      - "8088:8088"
      - "8089:8089"
    environment:
      WEBSITES: '[{"name":"Main","logPath":"/share/log/nginx/access.log","domains":["example.com"]}]'
    volumes:
      - ./nginx_logs/access.log:/share/log/nginx/access.log:ro
      - ./var/nginxpulse_data:/app/var/nginxpulse_data
    restart: unless-stopped

After starting, the frontend UI is at http://localhost:8088 and the backend API at http://localhost:8089.

Multi‑site configuration

Provide an array to the WEBSITES environment variable:

WEBSITES='[
  {"name":"Main","logPath":"/logs/main.log","domains":["www.example.com"]},
  {"name":"Blog","logPath":"/logs/blog.log","domains":["blog.example.com"]}
]'

Log paths can use wildcards (e.g., /logs/access-*.log) and compressed .gz files are parsed directly.

Remote log retrieval

NginxPulse can fetch logs from remote servers via SFTP, HTTP, or S3/OSS. Example SFTP configuration:

{
  "id":"sftp-main",
  "type":"sftp",
  "host":"1.2.3.4",
  "port":22,
  "user":"nginx",
  "auth":{"keyFile":"/secrets/id_rsa"},
  "path":"/var/log/nginx/access.log"
}

Push agent

A lightweight agent can run on internal or edge servers to push logs to the NginxPulse service in real time.

Custom log formats

Two ways to define non‑standard logs:

Direct log_format syntax

{"logFormat":"$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent"}

Regex with named groups

{"logRegex":"^(?P<ip>\\S+) - (?P<user>\\S+) \[(?P<time>[^\\]]+)\]..."}

Caddy support

Set logType: "caddy" to parse Caddy JSON logs.

Access control

ACCESS_KEYS='["your-secret-key"]'

Clients must include the X-NginxPulse-Key header to access the dashboard.

Common issues

Empty log details after startup – usually a permission problem. Grant read/write permissions, e.g.:

chmod -R 777 /path/to/logs /path/to/nginxpulse_data

PV/UV always zero – internal IPs are excluded by default. Set PV_EXCLUDE_IPS='[]' to include them.

Single‑binary deployment

Build a single executable (includes built‑in frontend) for amd64 and arm64:

./scripts/build_single.sh

References

GitHub repository: https://github.com/likaia/nginxpulse

Online demo: https://nginx-pulse.kaisir.cn/ (project has over 1.4k stars and is MIT‑licensed).