A Lightweight Nginx Log Analyzer Worth Trying

What is NginxPulse?

One‑sentence: a lightweight Nginx log analysis panel.

Real‑time PV/UV statistics

IP location lookup (ip2region locally, ip‑api for foreign IPs)

Client/browser parsing

Multi‑site support

Custom log format support

Tech Stack

Backend: Go + Gin. Frontend: Vue3 + Vite + PrimeVue. Database: a single SQLite file.

IP location lookup order: in‑memory cache → remote API batch lookup → fallback to local ip2region database.

Running the service

Docker

docker run -d --name nginxpulse \
 -p 8088:8088 \
 -p 8089:8089 \
 -e WEBSITES='[{"name":"主站","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":"主站","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

Frontend panel: http://localhost:8088. Backend API: http://localhost:8089.

Multi‑site configuration

WEBSITES='[
 {"name":"主站","logPath":"/logs/main.log","domains":["www.example.com"]},
 {"name":"博客","logPath":"/logs/blog.log","domains":["blog.example.com"]}
]'

Wildcard log paths (e.g., /logs/access-*.log) and compressed .gz logs are supported.

Remote log pull

Supports SFTP, HTTP, and 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 push logs from internal or edge servers to the NginxPulse service in real time.

Custom log formats

Two definition methods:

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

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

Caddy support

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

Access control

Define secret keys with ACCESS_KEYS='["your-secret-key"]' and include the X-NginxPulse-Key header in requests.

FAQ

Log details are empty after start – usually a permission issue. Example fix:

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

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

Single‑binary deployment

Build a self‑contained binary (frontend included) with: ./scripts/build_single.sh The binary supports both amd64 and arm64 platforms.

References

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

Online demo: https://nginx-pulse.kaisir.cn/

MIT‑licensed, approximately 1.4k stars.