📈 Nginx‑prometheus‑exporter

🎯 Purpose

NGINX Prometheus Exporter converts NGINX status data into Prometheus metrics so you can visualize web server health in Grafana and alert on failures later. Use it to monitor:

• Whether NGINX is reachable
• Connection load and behavior
• Request throughput trends
• Early signs of saturation or errors

🏗 Architecture

• NGINX exposes status data (typically via a status endpoint).
• NGINX Exporter scrapes that endpoint.
• Prometheus scrapes NGINX Exporter.
• Grafana reads metrics from Prometheus.

📊 What the Exporter Provides

Common metric families include:

• nginx_up
• nginx_connections_active
• nginx_connections_reading
• nginx_connections_writing
• nginx_connections_waiting
• nginx_connections_accepted
• nginx_connections_handled
• nginx_http_requests_total

⚙️ Prerequisites

• NGINX installed and running on target host
• NGINX status endpoint enabled and reachable by exporter
• Exporter service running on expected port
• Prometheus scrape target configured for nginx_exporter job
• Grafana datasource connected to Prometheus

🚀 Deployment

Example deployment flow:

Deploy or refresh reverse proxy hosts:

source /opt/python_3.12/bin/activate
ansible-playbook -i inventory/rproxy/inventory.ini playbooks/rproxy/deploy_rproxy.yml

Refresh Prometheus exporter targets:

source /opt/python_3.12/bin/activate
ansible-playbook -i inventory/rproxy/inventory.ini playbooks/prometheus/deploy_nginx_prometheus_exporter.yml

Syntax check:

source /opt/python_3.12/bin/activate
ansible-playbook --syntax-check -i inventory/rproxy/inventory.ini playbooks/rproxy/deploy_rproxy.yml

👉 See also: Adding NGINX Exporter to an Inventory

🔍 Prometheus Queries

Exporter health:

up{job="nginx_exporter"}

NGINX reachability:

nginx_up

Active connections:

nginx_connections_active

Request rate:

rate(nginx_http_requests_total[5m])

Total active connections:

sum(nginx_connections_active)

Top busy instances:

topk(5, nginx_connections_active)

📈 Grafana Dashboard Recommendations

Panels:

• Exporter Up (stat)
• NGINX Up (stat)
• Active Connections (time series)
• Request Rate (time series)
• Connection States (stacked)
• Instance Table

Variables: instance, group/environment, time range presets.

🧪 Operational Checks

On a target host:

Check exporter service:

systemctl status nginx-prometheus-exporter

Check exporter metrics:

curl -s http://127.0.0.1:<exporter_port>/metrics | head

Check NGINX status endpoint:

curl -s http://127.0.0.1:<nginx_status_port_or_path>

🛠 Troubleshooting

No data in Grafana:

• Prometheus target down
• Exporter not running
• Exporter cannot reach NGINX
• Wrong datasource/job labels

Exporter up but nginx_up = 0:

• Status endpoint unreachable
• Firewall/ACL blocking
• Wrong scrape URI

Intermittent drops:

• Network instability
• NGINX reload windows
• Host resource pressure

⭐ Best Practices

• Restrict status endpoint
• Use consistent instance labels
• Track both exporter health and nginx_up
• Add recording rules for high‑traffic environments

📝 Summary

NGINX Exporter provides lightweight visibility into NGINX health using Prometheus and Grafana. Start with exporter health, reachability, and connection/request trends, then layer alerting.