Set up Metrics Collection
Contains instructions for setting up the NGINX Controller Agent to collect metrics for NGINX Plus instances
- Before you can set up metrics collection, you first need to install and start the NGINX Controller Agent, so that the Agent can start pushing aggregated data to NGINX Controller.
Follow the steps in this guide to configure how metrics are collected and monitored.
In order to monitor an NGINX Plus instance, the NGINX Controller Agent needs to find the relevant NGINX control process and determine its key characteristics.
The Agent is able to automatically find all relevant NGINX configuration files, parse them, extract their logical structure, and send the associated JSON data to the Controller Server for further analysis and reporting.
To parse SSL certificate metadata, the NGINX Controller Agent uses standard
openssl(1) functions. SSL certificates are parsed and analyzed only when the corresponding settings are turned on. SSL certificate analysis is on by default.
To enable or disable analyzing SSL certs:
- Open the NGINX Controller user interface and log in.
- Select the NGINX Controller menu icon, then select Platform.
- On the Platform menu, select Agent.
- On the Default agent settings page, select or clear the Analyze SSL certificates box.
NGINX Controller uses the
/api location on the NGINX Plus instance to collect metrics.
When you push a configuration to an NGINX Plus instance, NGINX Controller automatically enables the
/api location for that instance.
/apilocation settings that NGINX Controller creates will override any settings that you have previously defined.
If you use NGINX Controller solely to monitor your NGINX Plus instances, you may need to enable the
/api location on your instances manually.
Refer to the Configuring the API section of the NGINX Plus Admin Guide for instructions.
For more information about the metrics list, refer to Overview: Metrics and Metadata.
You don’t have to specifically point the Agent to either the NGINX configuration or the NGINX log files. The Agent should detect their location automatically. However, you do need to make sure that the Agent can read the log files.
To do so, verify that either the
nginx user or the user defined in the NGINX config – such as
www-data – can read the log files. In addition, make sure that the log files are being written normally.
The Agent will try to detect the log format for a particular log, so that it can parse the log correctly and extract relevant metrics data.
Take the steps in this section to enable the NGINX Controller Agent to collect metrics from custom
Add a new access.log format to the NGINX configuration (or modify an existing one).
Add the desired NGINX variables to the log format. For example:
log_format main_ext '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for" ' '"$host" sn="$server_name" ' 'rt=$request_time ' 'ua="$upstream_addr" us="$upstream_status" ' 'ut="$upstream_response_time" ul="$upstream_response_length" ' 'cs=$upstream_cache_status' ;
Use the extended log format in your access log configuration:
access_log /var/log/nginx/access.log main_ext;Note:
By default, the Controller Agent processes all access logs that it finds in your log directory. If you define a new log file with the extended log format that contains entries that are already being logged to another access log, your metrics might be counted twice. Refer to the Agent configuration guide to learn how to exclude specific log files from processing.
Set the error.log log level to
error_log /var/log/nginx/error.log warn;
Reload your NGINX configuration:
service nginx reload
When the Controller Agent discovers these metrics, the NGINX Controller Analytics Dashboards Overview will automatically update with a predefined set of graphs. You can also use these metrics to build more specific set of custom Dashboards.
If you set up the Controller Agent to use Syslog, you need to set up the Controller Agent to collect metrics from Syslog.
Take the steps below to enable metrics collection from Syslog:
Edit the NGINX configuration file.
sysloglistener address as the first parameter to the access.log directive.
controllertag and your preferred log format:
access_log syslog:server=127.0.0.1:12000,tag=controller,severity=info main_ext;
service nginx reload
For more information, see Controlling NGINX.
To send the NGINX logs to both the existing logging facility and the NGINX Controller Agent, include a separate access.log directive for each destination.
This documentation applies to the following versions of NGINX Controller: 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, 3.15, 3.16, and 3.17.