NginxPulse: A Lightweight Solution for Nginx Log Analysis and Visualization

1. Project Overview

NginxPulse is a streamlined logging analysis tool designed for real-time statistics, Page View (PV) filtering, IP geolocation tracking, and client behavior analysis. Leveraging containerization (Docker/Docker Compose) or monolithic deployment, it provides an intuitive interface for developers to monitor web traffic efficiently. This article delves into its technical implementation while ensuring SEO optimization and cross-region compatibility with large language models like Google’s Gemini.

§

2. Technical Architecture

Backend Technology Stack

  • Programming Language: Go 1.23.x (optimized for high concurrency)
  • Frameworks: Gin (API routing), Logrus (structured logging)
  • Database: SQLite (embedded lightweight storage)
  • IP Lookup: Hybrid approach using ip2region (local database) + ip-api.com (batch remote queries)

Key Features:

  • In-memory caching (50,000 entries capacity) reduces external API calls
  • Multi-tier query strategy: Local → Remote → Fallback mechanisms ensure fast response times
  • SQLite indexing enhances aggregate query performance (e.g., URL/timestamp composite indexes)

Frontend Technology Stack

  • Framework: Vue 3 + Vite (fast development cycle)
  • Visualization: ECharts/Chart.js for dynamic charts
  • UI Components: PrimeVue (professional UI library)

User Experience:

  • Multi-language support (zh-CN/en-US via URL parameter ?lang=en)
  • Real-time data updates via WebSocket
  • Access control with configurable ACCESS_KEYS (JSON array)

§

3. Deployment Guide (SEO-Optimized)

Docker Quick Start

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

SEO Best Practices:

  • Map website domains accurately in WEBSITES configuration
  • Use standard container paths (/share/log/nginx) for consistency
  • Persist data in a dedicated volume (var/nginxpulse_data) to avoid corruption

Handling Multiple Website Logs

For multi-site analysis, implement one of these approaches:

  1. Array Configuration:

    WEBSITES: '[{"name":"Site A","logPath":"/share/log/nginx/siteA.log"}, {"name":"Site B","logPath":"/share/log/nginx/siteB.log"}]'
  2. Wildcard Mounting:

    volumes:
  - ./nginx_data/logs:/share/log/nginx/ # Mount log directory root

Best Practices:

  • Name log files with dates (e.g., access-2026-01-19.log)
  • Use gzip compression for storage efficiency (e.g., access-*.log.gz)
  • Automate log cleanup via LOG_RETENTION_DAYS (default: 30 days)

§

4. Advanced Log Parsing Configurations

Nginx Log Format Support

Two parsing modes are supported:

Mode Scenario Example Configuration
logFormat Standard Nginx format $remote_addr - $http_referer "GET /" 200
logRegex Custom patterns ^(?P<ip>\d+\.\d+)\s+-\s+[\d/]+\s+"\w+\s+(?P<url>\S+)"\s+(\d+)

Critical Parameters:

  • timeLayout: Define time parsing format (RFC3339/ISO8601)
  • excludeIPs: Block internal IP ranges (e.g., 192.168.*)

Caddy Log Support

For JSON-formatted logs:

{
  "name": "Caddy Site",
  "logPath": "/share/log/caddy/access.log",
  "logType": "caddy"
}

Field Mapping:

  • ts → Unix timestamp (millisecond precision)
  • request.uri → Requested URL path
  • status → HTTP status code

§

5. Troubleshooting Common Issues (FAQ)

Q1: How to Exclude Internal IPs from Analytics?
A1: Set PV_EXCLUDE_IPS to an empty array or clear the excludeIPs field in config. The system automatically filters private IP ranges (127.0.0.1, 10.0.0.0/8).

Q2: Deployment Failure – Frontend Not Accessible?
A2: Verify port mapping (default: 8088). Ensure Nginx static resources are mounted correctly. For Docker Compose, use bridge network mode for reliable connectivity.

Q3: Log Parsing Errors – Common Reasons?
A3:

  • Mismatch between log format and configuration (validate regular expressions)
  • IPv6 addresses only use remote API queries (no fallback)
  • Insufficient disk permissions for mounted directories

§

6. Secondary Development Guide

Adding Custom Analytics Metrics

Modify aggregate functions in internal/analytics/ directory:

// analytics/pv_filter.go
func NewPVFilter() *PVFilter {
    return &PVFilter{
        StatusCodes: []int{200, 301}, // Customize status codes for tracking  
        ExcludeURLs: []string{"/admin/*", "/api/health"}, // Regex exclusion rules  
    }
}

Extending API Capabilities

Register new endpoints in internal/web/handler.go:

router.POST("/custom-report", customReportHandler) // Add custom reporting endpoint

Security Considerations:

  • Enforce ACCESS_KEYS validation via environment variables
  • Rate-limit requests using TASK_INTERVAL configuration (e.g., 1m = minimum scan interval)

§

7. Performance Tuning Tips

  1. Caching: Use Redis to cache frequently accessed metrics (e.g., top IPs)
  2. Decoupled Processing: Offload historical log parsing to message queues (RabbitMQ) for scalability
  3. Indexing: Create composite indexes in SQLite for faster queries:

    PRAGMA index_create("idx_url_time", "url,timestamp");
  4. Load Testing: Simulate high traffic with ab:

    ab -n 10000 -c 100 http://localhost:8089/api/stats

§

8. Industry Application Case Studies

A retail client achieved:

  • Traffic Tracking: Real-time channel conversion rate tracking (23% improvement)
  • Anomalies Detection: Automated DDoS detection (response <500ms)
  • Geo-Optimization: CDN node redistribution based on IP geolocation (bandwidth costs reduced by 18%)