Updated January 29, 2014, 4:42 pm

NGINX Status

This post is going to be about creating a self updating nginx status page.

I have used lighttpd for a while and found that it has already been done before here. What I have done is, I took Markus' code, converted it to use nginx_status module and added two graphs using jqplot. The final result looks like this. So read on if you want to learn how it's done and get the source at the end.

First we need to make sure nginx is compiled with the "http_stub_status_module". To check if your nginx installation has this module, run the following command in the shell :

nginx -V
This will print out information about your nginx installation, if you see "--with-http_stub_status_module" in that list you're good.

Next we need to enable the status module so we can access it on the web. To do this you need to add the following to your nginx configuration file :

location /nginx_status {
  stub_status on;
  access_log   off;
  #uncomment and add an ip address if you want to block access to status page
  #allow SOME.IP.ADD.RESS; 
  #deny all; 
}
The previous code goes into your server configuration block, so you might have a server block that might look like this :
server {
    server_name www.yourdomain.com yourdomain.com;

    location / {
       ...
    }

    location /nginx_status {
        stub_status on;
        access_log off;
        #allow some.ip.add.ress;
        #deny all;
    }

    location ~ \.php$ {
        ...
    }
}
Once you setup your configuration file restart nginx and you should be able to see the output of the status module at "yourdomain.com/nginx_status". Here is the output of shadowytree.com/nginx_status :
Active connections: 1 
server accepts handled requests
 5177 5177 24710 
Reading: 0 Writing: 1 Waiting: 0 
You can get more info about the status module here.

Next is a php script that gets that raw info and server uptime and returns it as a json encoded string, so we can build the page and the graphs.

I am not going to explain the whole php script here you can take a look at the source if you like, but it looks like this :

//uptime.php
$serverUptime = getServerUptime();
					
$nginxUptime = getNGINXUptime();					

$nginxStatus = getNGINXStatus($nginxUptime['totalSeconds']);

echo json_encode(
	array(
		"server_uptime"=>$serverUptime,
		"nginx_uptime"=>$nginxUptime,
		"nginx_status"=>$nginxStatus
		)
	);
Each function does it's thing and than the whole thing is returned back, the function that parses the raw /nginx_status is getNGINXStatus.

Once this script is up and running, we can create a page that will call this method every 5 seconds to get the server status and update our page/graphs.

You can check the file status.php to see how the values are taken from the php script and filled into the page, also the graphs are updated every 5 seconds. There are a few variables that you can adjust in status.php, they are self-explanatory :

	// used in the graph as the upper limit for connections, you can adjust this 
	var MAX_CONNECTIONS=1000;
	
	// used in the graph as the upper limit for requests per second, you can adjust this 
	var MAX_REQUESTS_PER_SECOND=500;
	
	// set this to a different value to update faster or slower
	var UPDATE_INTERVAL=5;
		
	// history to keep in seconds , keep 1 hour of history for graphs
	var HISTORY = 3600;
By default, the page updates every 5 seconds, keeps one hour history for graphs, the connection graph has a range of 0-1000 and the requests graph has a range of 0-500. You can adjust these values depending on your server.

Here is the download link: nginx_status.zip

To install extract to your web root. The jqplot libraries included are not minified so you might want to get the minified versions.

And that's it. You should have a self updating nginx status page.

This post has been featured here