In modern infrastructure management, observability plays a critical role in maintaining web server health and ensuring optimal user experience. Prometheus, a powerful open-source monitoring and alerting toolkit, excels at collecting and querying time-series data. When integrated with Nginx, one of the most popular web servers and reverse proxies, it offers deep insights into web traffic and server performance.

This post targets intermediate to advanced users who want a technical deep dive into configuring Prometheus to scrape metrics from Nginx, enabling real-time monitoring and proactive alerting.

Why Monitor Nginx with Prometheus

Nginx serves as the backbone for many web applications, handling millions of requests per second in high-traffic environments. Monitoring key metrics such as request rates, response statuses, latency, and connection states is essential to:

  • Detect anomalies and performance bottlenecks
  • Optimize resource allocation
  • Automate alerting and incident response
  • Gain visibility into user traffic patterns

Prometheus’s pull-based scraping model combined with Nginx’s extensible metrics export capabilities make this integration a robust solution for scalable observability.

Preparing Nginx for Prometheus Metrics Export

By default, Nginx does not expose Prometheus-compatible metrics. To enable this:

  1. Use the Nginx Prometheus Exporter — an open-source exporter that scrapes Nginx’s stub_status endpoint and exposes Prometheus formatted metrics.
  2. Configure Nginx to expose the stub_status endpoint:
server {
    listen 127.0.0.1:8080;
    location /nginx_status {
        stub_status on;
        allow 127.0.0.1;  # Restrict access for security
        deny all;
    }
}
  1. Download and run the Prometheus Nginx Exporter:
wget https://github.com/nginxinc/nginx-prometheus-exporter/releases/latest/download/nginx-prometheus-exporter-linux-amd64.tar.gz
tar -xvf nginx-prometheus-exporter-linux-amd64.tar.gz
./nginx-prometheus-exporter -nginx.scrape-uri http://127.0.0.1:8080/nginx_status

This exporter will listen on port 9113 by default and expose metrics such as nginx_connections_active and nginx_requests_total.

Configuring Prometheus to Scrape Nginx Metrics

To integrate Nginx metrics into your Prometheus server, update your prometheus.yml configuration:

scrape_configs:
  - job_name: 'nginx'
    static_configs:
      - targets: ['localhost:9113']

Ensure the Prometheus server can reach the exporter endpoint. Reload Prometheus configuration or restart the server to apply changes.

Key Metrics to Monitor

Once integrated, Prometheus will collect critical metrics including:

  • nginx_connections_active: Current active connections
  • nginx_connections_accepted: Total accepted connections
  • nginx_connections_handled: Connections handled successfully
  • nginx_requests_total: Total HTTP requests processed
  • nginx_http_requests_total: Requests by HTTP status code (2xx, 3xx, 4xx, 5xx)
  • nginx_ingress_latency_seconds (if using custom Nginx setups with Lua or modules)

These metrics can be used to create dashboards and alerts in Grafana or Alertmanager, enabling you to visualize traffic trends and respond to performance degradation proactively.

Advanced Nginx Metrics with Lua and Custom Exporters

For advanced users, extending Nginx with the Lua module (ngx_http_lua_module) allows granular control over metrics, including:

  • Detailed request latency breakdowns
  • Per upstream server health
  • Custom labels for user sessions or request types

Example Lua snippet to expose latency histogram:

local prometheus = require("prometheus").init("prometheus_metrics")
local latency_histogram = prometheus:histogram("nginx_request_latency_seconds", "Request latency in seconds", {"method", "status"})

latency_histogram:observe(ngx.var.request_time, {ngx.req.get_method(), ngx.status})

This requires setting up an HTTP endpoint that Prometheus can scrape the metrics from, typically /metrics.

Best Practices for Production Deployment

  • Secure your metrics endpoint: Use firewall rules or authentication to restrict access.
  • Monitor exporter resource usage: The exporter should not add significant CPU or memory overhead.
  • Use relabeling in Prometheus: To enrich or filter metrics dynamically.
  • Leverage Grafana Dashboards: Pre-built dashboards for Nginx and Prometheus accelerate visualization.
  • Set alerting thresholds: For high error rates, increased latency, or connection spikes to prevent outages.

Conclusion

Integrating Prometheus with Nginx transforms raw web server metrics into actionable insights, empowering teams to maintain high availability and performance. By leveraging the Prometheus Nginx Exporter and optionally extending metrics with Lua scripting, you can achieve comprehensive observability tailored to complex production environments.

Investing time in this integration pays dividends by reducing downtime, improving user experience, and enabling data-driven infrastructure decisions. Start monitoring your Nginx servers with Prometheus today and unlock the full potential of your web traffic analytics.