v1.2.0

What's New

New Metrics

• Slow request tracking - nginx_server_zone_slow_requests_total counts requests exceeding configurable threshold (default 1s)
• Request size histogram - nginx_server_zone_request_length_bytes_bucket tracks request body size distribution with buckets from 100B to 100MB
• Upstream health gauge - nginx_upstream_health provides calculated health status (1=healthy, 0=unhealthy) based on failure rate threshold (default 10%)

Observability Examples

• Prometheus alerting rules - Pre-built alerting rules (examples/prometheus-alerts.yml) covering availability, errors, latency, upstream health, connections, cache, rate limiting, SSL/TLS, and traffic anomalies
• Grafana dashboard - Pre-built dashboard (examples/grafana-dashboard.json) with overview, request, latency, upstream, connection, and SSL/TLS panels

Installation

luarocks install lua-resty-ngxstats

Or with Docker:

docker pull ghcr.io/abtreece/lua-resty-ngxstats:v1.2.0

See CHANGELOG.md for full details.

v1.1.0 - New Metrics & Infrastructure

What's New

This release adds new metrics, improves Docker infrastructure, and restructures the project to follow lua-resty-* conventions for LuaRocks compatibility.

New Metrics

• Request timing - nginx_server_zone_request_time_seconds tracks total request processing time per zone
• SSL/TLS protocol tracking - nginx_server_zone_ssl_total tracks requests by SSL/TLS protocol version (TLSv1.2, TLSv1.3, etc.)

Docker Improvements

• Added .dockerignore to reduce image size
• Added OCI image labels (title, description, version, source, license)
• Added HEALTHCHECK directive for container health monitoring

Deployment Examples

New examples/ directory with ready-to-use configurations:

• docker-compose.yml - Complete stack with Prometheus and Grafana
• prometheus.yml - Prometheus scrape configuration
• nginx.conf.example - Production-ready NGINX configuration

Breaking Changes

• Module namespace changed from stats.* to resty.ngxstats.*
• Modules moved from lib/resty/*.lua to lib/resty/ngxstats/

If you were requiring modules directly (unlikely for most users), update your requires:

-- Before
local common = require "stats.common"

-- After
local common = require "resty.ngxstats.common"

LuaRocks

This release includes a proper .rockspec file for LuaRocks distribution.

Installation

Docker

docker pull ghcr.io/abtreece/lua-resty-ngxstats:v1.1.0

Manual

git clone https://github.com/abtreece/lua-resty-ngxstats.git
cd lua-resty-ngxstats
git checkout v1.1.0
cp -r lib/resty /path/to/openresty/lualib/

Full Changelog

v1.0.0...v1.1.0

v1.0.0 - NGINX Metrics Exporter

Overview

This release transforms lua-resty-ngxstats into a production-ready NGINX metrics exporter with Prometheus format support, comprehensive testing, CI/CD, and complete documentation.

🚨 Breaking Changes

The /status endpoint now outputs Prometheus text format instead of JSON.

Migration

Before (JSON):

curl http://localhost:8080/status | jq '.'

After (Prometheus):

curl http://localhost:8080/status

Prometheus Configuration:

scrape_configs:
  - job_name: 'nginx'
    static_configs:
      - targets: ['localhost:8080']
    metrics_path: '/status'

---

✨ Highlights

New Features

• ✅ Prometheus text exposition format with HELP and TYPE comments
• ✅ Cache metrics - Track HIT, MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED
• ✅ HTTP method tracking - Monitor GET, POST, PUT, DELETE, etc.
• ✅ 50+ unit tests with busted framework
• ✅ GitHub Actions CI/CD - Automated linting, testing, and Docker builds
• ✅ Complete documentation - README, CONTRIBUTING, CHANGELOG

Critical Bug Fixes

• 🐛 Fixed crash from undefined response.exit() in status.lua
• 🐛 Fixed requests.total metric using wrong variable
• 🐛 Fixed nginx.conf ACL logic error
• 🐛 Added comprehensive error handling to shared memory operations

Code Quality Improvements

• 🧹 Removed all dead and commented-out code
• 🧹 Fixed global variables (converted all to local)
• 🧹 Converted all scripts to proper testable modules
• 🧹 Added input validation with safe conversion helpers
• 🧹 Added comprehensive function documentation
• 🧹 luacheck linting support

---

📊 Metrics Collected

Connection Metrics

• nginx_connections_active (gauge)
• nginx_connections_accepted (counter)
• nginx_connections_handled (counter)
• nginx_connections_reading (gauge)
• nginx_connections_writing (gauge)
• nginx_connections_idle (gauge)

Request Metrics

• nginx_requests_total (counter)
• nginx_requests_current (gauge)

Server Zone Metrics

• nginx_server_zone_requests_total{zone} (counter)
• nginx_server_zone_bytes_received{zone} (counter)
• nginx_server_zone_bytes_sent{zone} (counter)
• nginx_server_zone_responses_total{zone,status} (counter)
• nginx_server_zone_methods_total{zone,method} (counter) ⭐ NEW
• nginx_server_zone_cache_total{zone,cache_status} (counter) ⭐ NEW

Upstream Metrics

• nginx_upstream_requests_total{upstream} (counter)
• nginx_upstream_response_time_seconds{upstream} (counter)
• nginx_upstream_connect_time_seconds{upstream} (counter)
• nginx_upstream_queue_time_seconds{upstream} (counter)
• nginx_upstream_bytes_sent{upstream} (counter)
• nginx_upstream_bytes_received{upstream} (counter)
• nginx_upstream_responses_total{upstream,status} (counter)
• nginx_upstream_server_info{upstream,server} (gauge)

---

🚀 Quick Start

Docker (Recommended)

# Build and run
make build
make run_dev

# Generate test traffic
./test.sh

# View metrics
curl http://localhost:8080/status

Manual Installation

http {
    lua_shared_dict ngx_stats 10m;
    lua_package_path '/etc/nginx/lua/?.lua;;';
    init_by_lua_file /etc/nginx/lua/stats/init.lua;
    
    server {
        log_by_lua_file /etc/nginx/lua/stats/log.lua;
    }
    
    server {
        listen 8080;
        location /status {
            content_by_lua_file /etc/nginx/lua/stats/show.lua;
        }
        access_by_lua_file /etc/nginx/lua/stats/status.lua;
    }
}

---

📈 Performance

• Overhead: < 1% CPU per request
• Memory: ~200 bytes per unique metric
• Latency: < 1ms added to request processing

---

📚 Documentation

• README - Complete installation and usage guide
• CONTRIBUTING - Development guide
• CHANGELOG - Detailed change history

---

🙏 Thanks

Thank you to everyone who has used and supported this project!

Full Changelog: e263311...v1.0.0