How to Use nginx stub_status for Basic Server Metrics

To use nginx stub_status, enable the stub_status module in your nginx configuration by adding a location block with stub_status;. Then access the URL to see real-time server metrics like active connections and requests.

Syntax

The stub_status directive is used inside a location block in the nginx configuration. It enables a simple status page that shows basic server metrics.

Key parts:

• location /status/ { ... }: Defines the URL path to access the status page.
• stub_status;: Enables the stub status module for that location.
• allow and deny: Optional directives to restrict access.

nginx

location /status/ {
    stub_status;
    allow 127.0.0.1;
    deny all;
}

Example

This example shows a complete nginx server block with stub_status enabled at /status/. It restricts access to localhost for security.

nginx

server {
    listen 80;
    server_name localhost;

    location /status/ {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}

Output

Active connections: 1 
server accepts handled requests
 10 10 20 
Reading: 0 Writing: 1 Waiting: 0

Common Pitfalls

• Not restricting access: Leaving the status page open can expose server info to anyone. Always use allow and deny to limit access.
• Missing stub_status; directive: Without this, the status page won't work.
• Wrong location path: Access the exact path defined in location, otherwise you get 404.

nginx

location /status/ {
    # Wrong: missing stub_status directive
    allow 127.0.0.1;
    deny all;
}

# Correct:
location /status/ {
    stub_status;
    allow 127.0.0.1;
    deny all;
}

Quick Reference

Directive	Description
stub_status;	Enables the stub status module in a location
allow ;	Allows access from specified IP address
deny all;	Denies access from all other IPs
location /path/ { ... }	Defines the URL path for the status page

Key Takeaways

Enable stub_status inside a location block with the stub_status; directive.

Restrict access to the status page using allow and deny directives for security.

Access the exact URL path defined in the location block to see metrics.

The status page shows active connections, accepted requests, and current reading/writing states.

Without stub_status; the status page will not work even if the location exists.