Slow NGINX? How to monitor connections with stub_status
Is your NGINX responding slowly? Learn how to use the stub_status module to identify bottlenecks in concurrent connections and optimize your server performance.
Summary
- The stub_status module provides real-time metrics on web server traffic.
- High counts of reading or writing connections often indicate backend processing bottlenecks.
- Enabling the module requires only a simple directive in your NGINX configuration file.
- Constant monitoring prevents concurrent connection limits from causing unexpected downtime.
- Tracking via stub_status complements other network diagnostic tools available in Linux.
Why is your NGINX responding slowly?
When a web server starts showing high latency, the first reaction is often to restart the service. However, without understanding whether the issue stems from stuck connections, resource exhaustion, or backend bottlenecks, you are merely applying a band-aid. NGINX, famous for its performance, includes a native tool called stub_status, which acts as a basic dashboard to understand what is happening under the hood.
Understanding the stub_status module in practice
The stub_status module displays the current state of connections in a minimalist way. It shows, for example, how many connections are reading, how many are being processed, and how many are idle (keep-alive). In practice, this means you can instantly see if your server is being overwhelmed by unexpected traffic or if a slow application is clogging your workers.
To check if your NGINX binary has this module, run the command nginx -V 2>&1 | grep -o with-http_stub_status_module. If the command returns the string, you are ready to configure it. Otherwise, you might need to recompile NGINX, although most modern distribution packages come with this functionality enabled by default.
How to enable and check status
Setting up monitoring is a process of just a few minutes. You should create or edit a location block within your configuration file (usually in /etc/nginx/sites-available/default or similar). Add the following code snippet:
location /nginx_status { stub_status; allow 127.0.0.1; deny all; }After reloading NGINX with nginx -t && systemctl reload nginx, you will be able to access http://localhost/nginx_status. Remember to restrict access to this endpoint to your IP address to avoid exposing internal server metrics to curious individuals or attackers. The result will be simple text with numbers that reveal your web server's "pulse".
Interpreting the bottlenecks
When looking at the metrics, focus on the connection states. If the number of reading connections is high, the server is struggling to read client headers, which might point to network issues. If the number of writing connections is high and constant, your NGINX might be waiting for a slow backend to process requests (like PHP-FPM or a cluster of microservices). This is quite common in complex systems where the bottleneck isn't the web server itself, but how the system manages load and pods.
The next step in investigation
The stub_status module is just the beginning of the journey. If you identify that the problem lies not in NGINX, but in the TCP connections reaching or leaving the server, use deeper tools for diagnostics. You can perform a detailed network inspection using the tcpdump command to capture specific packets, or monitor TCP connection states with the ss utility, ensuring a complete view of the communication stack.
Conclusion
Mastering basic server monitoring is a key differentiator for any engineer seeking stability. By integrating stub_status into your observability routines, you stop guessing where the error lies and start using concrete data to make decisions, whether by adjusting timeouts or increasing server capacity.
Infrastructure stability doesn't come just from powerful hardware, but from intelligent resource management. Use native metrics, automate collection if necessary, and never ignore the signals your system sends before a major failure occurs.