Monitoring Nginx

This article will help you get the Nginx plugin for sd-agent configured and returning metrics

Installing the nginx plugin package

Install the nginx plugin on Debian/Ubuntu:

sudo apt-get install sd-agent-nginx

Install the nginx plugin on RHEL/CentOS:

sudo yum install sd-agent-nginx

Read more about agent plugins.

Configuring the agent to monitor NGINX

The agent can parse the Nginx HttpStubStatusModule output to show the current requests per second and number of connections. It also requires some additional configuration of your nginx server.

1. You first need to ensure the HttpStubStatusModule module is installed. This is not available by default and must be compiled in with the configure line:

--with-http_stub_status_module

Or by installing the 'nginx-extras' package on Debian/Ubuntu systems.

• You can check whether HttpStubStatusModule is installed with the following command:

nginx -V 2>&1 | grep -o with-http_stub_status_module

If you get a result you've got it installed already.

2. Adding the following line to your /etc/nginx/nginx.conf file within a http { } block:

server {
        listen       127.0.0.1:80;
        listen       [::1]:80;
        server_name  localhost;

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

• This will allow the status output to be accessed from http://localhost/nginx_status

You will now need to restart your nginx web server to allow the changes to take effect.

3. The config file /etc/sd-agent/conf.d/nginx.yaml will already be configured to use http://localhost/nginx_status as the status URL. If you have configured the nginx status on another URL, you should amend as necessary.

4. Restart the agent

sudo /etc/init.d/sd-agent restart

or

sudo systemctl restart sd-agent

NGINX Plus

Nginx Plus customers can use the extended http_status_module for more insightful metrics. Server Density supports parsing the data here, as long as you have followed the above steps the agent will automatically collect these metrics with no further configuration required.

Verifying the configuration
Execute info to verify the configuration with the following:

sudo /etc/init.d/sd-agent info 

or

/usr/share/python/sd-agent/agent.py info

If the agent has been configured correctly you'll see an output such as:

nginx
-----
  - instance #0 [OK]
  - Collected * metrics

You can also view the metrics returned with the following command:

sudo -u sd-agent /usr/share/python/sd-agent/agent.py check nginx

Configuring graphs

Click the name of your server from the Devices list in your Server Density account then go to the Metrics tab. Click the + Graph button on the right then choose the nginx metrics to display the graphs. The metrics will also be available to select when building dashboard graphs.

Monitored metrics

Metric	Values
nginx.connections.accepted The total number of accepted client connections.	connection / None Type: float
nginx.connections.active The current number of active client connections.	connection / None Type: float
nginx.connections.dropped The total number of dropped client connections.	connection / None Type: float
nginx.connections.idle The current number of idle client connections.	connection / None Type: float
nginx.generation The total number of configuration reloads.	None / None Type: float
nginx.load_timestamp Time of the last reload of configuration (time since Epoch).	millisecond / None Type: float
nginx.net.conn_dropped_per_s	/ second Type: float
nginx.net.conn_opened_per_s	/ second Type: float
nginx.net.connections	/ Type: float
nginx.net.reading	/ Type: float
nginx.net.request_per_s	/ second Type: float
nginx.net.waiting	/ Type: float
nginx.net.writing	/ Type: float
nginx.pid The ID of the worker process that handled status request.	None / None Type: float
nginx.processes.respawned The total number of abnormally terminated and respawned child processes.	process / None Type: float
nginx.requests.current The current number of client requests.	request / None Type: float
nginx.requests.total The total number of client requests.	request / None Type: float
nginx.server_zone.discarded The total number of requests completed without sending a response.	request / None Type: float
nginx.server_zone.processing The number of client requests that are currently being processed.	request / None Type: float
nginx.server_zone.received The total amount of data received from clients.	byte / None Type: float
nginx.server_zone.requests The total number of client requests received from clients.	request / None Type: float
nginx.server_zone.responses.1xx The number of responses with 1xx status code.	response / None Type: float
nginx.server_zone.responses.2xx The number of responses with 2xx status code.	response / None Type: float
nginx.server_zone.responses.3xx The number of responses with 3xx status code.	response / None Type: float
nginx.server_zone.responses.4xx The number of responses with 4xx status code.	response / None Type: float
nginx.server_zone.responses.5xx The number of responses with 5xx status code.	response / None Type: float
nginx.server_zone.responses.total The total number of responses sent to clients.	response / None Type: float
nginx.server_zone.sent The total amount of data sent to clients.	byte / None Type: float
nginx.ssl.handshakes The total number of successful SSL handshakes.	None / None Type: float
nginx.ssl.handshakes_failed The total number of failed SSL handshakes.	None / None Type: float
nginx.ssl.session_reuses The total number of session reuses during SSL handshake.	None / None Type: float
nginx.timestamp Current time since Epoch.	millisecond / None Type: float
nginx.upstream.keepalive The current number of idle keepalive connections.	connection / None Type: float
nginx.upstream.peers.active The current number of active connections.	connection / None Type: float
nginx.upstream.peers.backup A boolean value indicating whether the server is a backup server.	None / None Type: float
nginx.upstream.peers.downstart The time (since Epoch) when the server became “unavail” or “unhealthy”.	millisecond / None Type: float
nginx.upstream.peers.downtime Total time the server was in the “unavail” and “unhealthy” states.	millisecond / None Type: float
nginx.upstream.peers.fails The total number of unsuccessful attempts to communicate with the server.	None / None Type: float
nginx.upstream.peers.health_checks.checks The total number of health check requests made.	None / None Type: float
nginx.upstream.peers.health_checks.fails The number of failed health checks.	None / None Type: float
nginx.upstream.peers.health_checks.last_passed Boolean indicating if the last health check request was successful and passed tests.	None / None Type: float
nginx.upstream.peers.health_checks.unhealthy How many times the server became unhealthy (state “unhealthy”).	None / None Type: float
nginx.upstream.peers.id The ID of the server.	None / None Type: float
nginx.upstream.peers.received The total amount of data received from this server.	byte / None Type: float
nginx.upstream.peers.requests The total number of client requests forwarded to this server.	request / None Type: float
nginx.upstream.peers.responses.1xx The number of responses with 1xx status code.	response / None Type: float
nginx.upstream.peers.responses.1xx_count The number of responses with 1xx status code (shown as count).	response / None Type: float
nginx.upstream.peers.responses.2xx The number of responses with 2xx status code.	response / None Type: float
nginx.upstream.peers.responses.2xx_count The number of responses with 2xx status code (shown as count).	response / None Type: float
nginx.upstream.peers.responses.3xx The number of responses with 3xx status code.	response / None Type: float
nginx.upstream.peers.responses.3xx_count The number of responses with 3xx status code (shown as count).	response / None Type: float
nginx.upstream.peers.responses.4xx The number of responses with 4xx status code.	response / None Type: float
nginx.upstream.peers.responses.4xx_count The number of responses with 4xx status code (shown as count).	response / None Type: float
nginx.upstream.peers.responses.5xx The number of responses with 5xx status code.	response / None Type: float
nginx.upstream.peers.responses.5xx_count The number of responses with 5xx status code (shown as count).	response / None Type: float
nginx.upstream.peers.responses.total The total number of responses obtained from this server.	response / None Type: float
nginx.upstream.peers.selected The time (since Epoch) when the server was last selected to process a request (1.7.5).	millisecond / None Type: float
nginx.upstream.peers.sent The total amount of data sent to this server.	byte / None Type: float
nginx.upstream.peers.unavail How many times the server became unavailable for client requests (state “unavail”) due to the number of unsuccessful attempts reaching the max_fails threshold.	None / None Type: float
nginx.upstream.peers.weight Weight of the server.	None / None Type: float
nginx.version Version of nginx.	None / None Type: float

Metrics Conversion

Please refer to the metrics conversion document to map old metrics names to the new metric names.