Nginx Status: The Complete Guide to Monitoring, Configuration & Performance Analytics

Understanding nginx status is critical for anyone managing high-traffic web infrastructure. Whether you're running a single VPS or a distributed CDN, the nginx status module provides essential visibility into connection counts, request rates, and server health in real time.

This guide covers everything from basic stub_status configuration to advanced monitoring integrations with Prometheus, Grafana, and Zabbix. We'll compare implementation approaches, analyze performance trade-offs, and answer the most common questions from DevOps engineers and system administrators.

Key Takeaways

• stub_status module is built into most nginx installations and requires only a single location block to enable
• Active connections metric is the most critical indicator of server health and potential DDoS attacks
• Custom status pages outperform default stub_status for production monitoring due to JSON output and extended metrics
• nginx-status-exporter bridges legacy stub_status with modern Prometheus-based monitoring stacks
• Security must be enforced — status endpoints should never be publicly accessible without IP whitelisting or basic auth

What Is Nginx Status?

Nginx status refers to the server's operational state as reported through built-in monitoring endpoints and external metrics exporters. The core mechanism is the stub_status module, which exposes concise statistics about current connections, accepted requests, and handled traffic.

Unlike full-featured monitoring agents, nginx status is lightweight, requires zero additional dependencies, and can be enabled in under five minutes. However, its simplicity comes with limitations that enterprise environments often need to work around through custom implementations.

How Nginx Status Differs from Nginx Plus Status

The open-source Nginx community edition provides basic stub_status endpoints, while Nginx Plus offers an advanced status API with detailed connection tracking, upstream health checks, and real-time process-level metrics. Understanding this distinction is essential when architecting monitoring solutions at scale.

Enabling stub_status: Configuration Guide

Activating nginx status monitoring requires a single configuration block in your server context. The default path is typically /nginx_status, though you can customize this for security through path obfuscation.

Basic Configuration

server {
    listen 8080;
    server_name localhost;

    location /nginx_status {
        stub_status on;
        allow 127.0.0.1;
        allow 10.0.0.0/8;
        deny all;
    }
}

Production Hardening Checklist

• Restrict access to monitoring subnet via allow/deny directives
• Enable HTTPS for status endpoint in production environments
• Add basic_auth credentials for additional access control layer
• Implement rate limiting to prevent status endpoint abuse
• Log access to status endpoint for audit trails
• Set X-Accel-Redirect or reverse proxy header for internal routing
• Exclude status endpoint from traffic analytics
• Test configuration with nginx -t before reloading

Understanding Nginx Status Output

When you query the status endpoint, you'll receive a plain-text response with three critical metrics. Each value serves a specific diagnostic purpose in production monitoring.

Core Metrics Explained

Sample Response Format

Active connections: 256 
server accepts handled requests
 1927696 1927696 5849623 
Reading: 3 Writing: 127 Waiting: 126

The Waiting count represents keep-alive connections, which is normal behavior. A high Waiting-to-Active ratio may indicate slow client applications or network latency issues.

Advanced: Custom Nginx Status Pages

For production environments requiring extended metrics, consider implementing a custom status page using $upstream_response_time, $request_time, and other built-in variables. These provide application-layer visibility that stub_status cannot offer.

JSON Status Endpoint Example

location /api/nginx-status {
    stub_status json;
    default_type application/json;
    
    access_log off;
    allow 10.0.0.0/8;
    deny all;
}

Some nginx builds support the json parameter with stub_status, returning structured output compatible with automated monitoring tools. Verify your nginx version supports this feature with nginx -V | grep stub_status.

Monitoring Integration: Prometheus & Grafana

The industry standard for nginx monitoring combines nginx-status-exporter with Prometheus and Grafana. This stack provides historical trending, alerting rules, and customizable dashboards without licensing costs.

Architecture Overview

The exporter queries the stub_status endpoint on each nginx instance, transforms the metrics into Prometheus format, and exposes them on a configurable port (typically 9113). Prometheus scrapes these metrics at regular intervals, while Grafana visualizes the data with predefined dashboards.

Deployment Checklist

• Install nginx-prometheus-exporter via