Nginx http_status_module statistics

Monitoring Nginx Performance with http_status_module Statistics

Learn how to enable and interpret statistics from Nginx's http_status_module to monitor server health and performance.

Nginx is a powerful, high-performance HTTP server and reverse proxy. To ensure its optimal operation and troubleshoot issues, it's crucial to monitor its activity. The http_status_module (also known as ngx_http_stub_status_module) provides a simple yet effective way to gather basic statistics about Nginx's current state. This article will guide you through enabling this module, configuring its access, and understanding the metrics it provides.

Enabling the http_status_module

The http_status_module is typically compiled into Nginx by default. However, if you've compiled Nginx from source, you might need to explicitly include it using the --with-http_stub_status_module flag during the ./configure step. Once confirmed, you'll need to configure a location block in your Nginx configuration to expose these statistics.

server {
    listen 80;
    server_name your_domain.com;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Basic Nginx configuration to expose status page

Understanding Nginx Status Metrics

Once configured, accessing the /nginx_status endpoint (e.g., http://localhost/nginx_status from the allowed IP) will display a simple text output. This output provides several key metrics that offer insights into your Nginx server's activity. Let's break down what each metric means.

Active connections: 2
server accepts handled requests
 100 100 50
Reading: 0 Writing: 1 Waiting: 1

Example output from the Nginx status page

flowchart LR
    A["Active connections"] --> B["Total active client connections"];
    C["server"] --> D["Total Nginx servers started (always 1)"];
    E["accepts"] --> F["Total accepted client connections"];
    G["handled"] --> H["Total handled connections (may be less than accepts if worker_connections limit is reached)"];
    I["requests"] --> J["Total client requests"];
    K["Reading"] --> L["Connections where Nginx is reading request headers"];
    M["Writing"] --> N["Connections where Nginx is writing response to client"];
    O["Waiting"] --> P["Idle client connections, waiting for a request"];

Breakdown of Nginx http_status_module metrics

Interpreting the Statistics for Performance Monitoring

These raw statistics, while simple, can be incredibly useful for basic performance monitoring and troubleshooting. By observing trends and sudden changes, you can identify potential bottlenecks or issues.

• Active connections: A high number indicates heavy load. If this consistently approaches your worker_connections limit, you might need to scale up or optimize your Nginx configuration.
• accepts vs. handled: Ideally, these numbers should be equal. If handled is significantly lower than accepts, it suggests that Nginx is dropping connections, likely due to resource exhaustion (e.g., worker_connections limit).
• requests: This gives you a total count of all requests processed by Nginx since it started. A steady increase is normal.
• Reading, Writing, Waiting: These provide a snapshot of connection states. A high Waiting count is generally good, indicating Nginx has idle connections ready to serve new requests. A high Reading or Writing count suggests active data transfer. If Reading or Writing are consistently high with low Waiting, it could indicate slow clients or backend processing.