End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller API Management Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller API- Management customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.
End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller Application Delivery Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller Application Delivery customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

Set up Metrics Collection

Contains instructions for setting up the NGINX Controller Agent to collect metrics for NGINX Plus instances.

Before You Begin

Objectives

Follow the steps in this guide to configure how metrics are collected and monitored.

Configuring NGINX for Metrics Collection

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.

SSL Certificate Parsing and Analysis

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:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Agent.
  4. On the Default agent settings page, select or clear the Analyze SSL certificates box.

Metrics from /api

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.

Note:
The /api location 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.

Metrics from access.log and error.log

The NGINX Controller Agent collects NGINX metrics from the access.log and the error.log by default.

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.

Enable Custom access.log Metrics

Some metrics included in the NGINX Metrics reference are not available unless the corresponding variables are included in a custom access.log format in the NGINX config.

See Also:
.

Take the steps in this section to enable the NGINX Controller Agent to collect metrics from custom access.log variables.

  1. Add a new access.log format to the NGINX configuration (or modify an existing one).

  2. 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' ;

  3. 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.

  4. Set the error.log log level to warn.

    error_log /var/log/nginx/error.log warn;

  5. 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.

Collect Metrics from Syslog

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:

  1. Edit the NGINX configuration file.

    1. Specify the syslog listener address as the first parameter to the access.log directive.

    2. Include the controller tag and your preferred log format:

      access_log syslog:server=127.0.0.1:12000,tag=controller,severity=info main_ext;

  2. Reload NGINX:

    service nginx reload

    For more information, see Controlling NGINX.

Note:
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.

What’s Next