Skip to main content

Nginx Plus Restapi

Overview​

NGINX Plus is a software load balancer, web server, and content cache built on top of open source NGINX.

The Centreon Plugin and Plugin-Packs rely on the Nginx Plus Rest API to collect the status of the Nginx resources.

Plugin-Pack Assets​

Monitored Objects​

  • Applications
  • Web Server
  • Load Balancer
  • Content cache

Collected Metrics​

More information about collected metrics is available in the official Nginx Plus API documentation: https://docs.nginx.com/nginx/admin-guide/load-balancer/dynamic-configuration-api/

Metric nameDescription
connections.active.countNumber of active connections
connections.idle.countNumber of idle connections
connections.accepted.countNumber of accepted connections
connections.dropped.countNumber of dropped connections

Prerequisites​

A service account is required to request the Nginx Plus API. It needs to have sufficient reading privileges in the environment. More infomation is avaible in official Nginx documentation : https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#getting-statistics-with-the-api

Setup​

  1. Install the Centreon Plugin on every poller monitoring Nginx Plus resources: :
yum install centreon-plugin-Applications-Nginx-Plus-Restapi.noarch
  1. On the Centreon Web interface in "Configuration > Plugin packs > Manager", install the Nginx Plus Plugin-Pack

Configuration​

This Plugin-Pack is designed to have in Centreon one host per Nginx Plus environment. Adding a host into Centreon, link it to the template named App-Nginx-Plus-Restapi-custom. Once the template applied, some Macros have to be configured:

MandatoryNameDescription
XAPIPORTPort used (Default: 443)
XAPIPROTOSpecify https if needed (Default: 'https')
XAPIUSERNAMENginx basic username
XAPIPASSWORDNginx basic password.
XAPIPATHSpecify api path (Default: '/api/6')
APIEXTRAOPTIONSAny extra option you may want to add to the command (eg. a --verbose flag)

FAQ​

How to test the Plugin and what are the main options for ?​

Once the Plugin installed, log into your poller using the centreon-engine user account and test by running the following command (Parameters such as api-username or api-path have to be adjusted):

/usr/lib/centreon/plugins/centreon_nginx_plus_restapi.pl \
--plugin=apps::nginx::nginxplus::restapi::plugin \
--mode=connections \
--hostname='mynginxplus.com' \
--port='443' \
--proto='https' \
--api-username='myapiuser' \
--api-password='myapipassword' \
--api-path='/api/6' \
--warning-active='60' \
--critical-active='80'
--warning-idle='8' \
--critical-idle='10' \
--warning-accepted='50'
--critical-accepted='65' \
--warning-dropped='3' \
--critical-dropped='5' \
--verbose

OK: Active : 5, Idle : 0, Accepted : 5, Dropped : 0|
'connections.active.count'=5;;60;80; 'connections.idle.count'=1;;8;10; 'connections.accepted.count'=5;;50;65; 'connections.dropped.count'=0;;3;5;

The above command checks the Nginx PLus connections (--mode=connections). It uses an api-username (--api-username='myapiuser'), an api-password (--api-password='myapipassword') and it connects to the host mynginxplus.com (--hostname='mynginxplus.com') on the port 443 (--port='/443') on the url /api/6 (--api-path='/api/6') using https (--proto='https'). This command will trigger a WARNING alarm if the active connections increase to 60 (--warning-active='60') and a CRITICAL alarm if it increases to 80 (--critical-active='80').

All the options that can be used with this plugin can be found over the --help command:

/usr/lib/centreon/plugins/centreon_nginx_plus_restapi.pl --plugin=apps::nginx::nginxplus::restapi::plugin 
--mode=connections --help

Why do I get the following error:​

UNKNOWN: 500 Can't connect to mynginxplus.com:443​

This error message means that the Centreon Plugin couldn't successfully connect to the Nginx Plus API. Check that no third party device (such as a firewall) is blocking the request. A proxy connection may also be necessary to connect to the API. This can be done by using the --proxyurl option in the command.

UNKNOWN: 501 Protocol scheme 'connect' is not supported |​

When using a proxy to connect to the Nginx Plus API, this error message means that the Centreon Plugin library does not support the proxy connection protocol.

In order to prevent this issue, use the curl HTTP backend by adding the following option to the command: --http-backend='curl'.

How do I remove the count perfdatas if I want to filter on just one application ?​

The Plugin adds the count of objects by default. This can be useless if the objects are filtered with the --filter-name parameter. Therefore, these useless perfdatas can be omitted by adding a perfdata filter : --filter-perfdata='^$'.