Install NGINX Plus Metrics Module
Follow the steps in this guide to install the NGINX Plus dynamic metrics module and configure NGINX Agent to push app-centric metrics to NGINX Management Suite.
The NGINX Plus metrics module is a dynamic module that you can install on your NGINX Plus data plane instances. The metrics module reports advanced, app-centric metrics and dimensions like “application name” or “gateway” to the NGINX Agent, which then aggregates and publishes the data to the NGINX Management Suite. Advanced, app-centric metrics are used by particular NGINX Management Suite modules, such as API Connectivity Manager, for features associated with HTTP requests.
Complete the following prerequisites before proceeding with the steps in this guide. This guide assumes that you have NGINX Management Suite installed and configured.
Check that your NGINX data plane instances are running NGINX Plus R24 or later.
To see which version of NGINX Plus is running on your instance, run the following command:
ps aux | grep nginx
The NGINX Plus metrics module works with the following Linux distributions:
Distribution Version(s) Amazon Linux 2 LTS CentOS 7.4 and later in the 7.x family Debian 10 buster-slim, 11 bullseye-slim RHEL 8.x and later in the 8.x family Ubuntu 18.08, 20.04, 22.04
Verify that NGINX Agent is installed on each NGINX Plus instance.
Before you install the NGINX Plus metrics module, you’ll need to stop the NGINX Agent process on the data plane instance.
Do not push configuration changes to the impacted instance, or any instance group that contains the impacted instance, while the
nginx-agent process is stopped.
Open an SSH connection to the data plane host and log in.
Run the following command to check whether NGINX Agent is running:
ps aux | grep nginx-agent
Run the command below to stop NGINX Agent:
sudo systemctl stop nginx-agent
Select the tab matching your Linux distribution, then follow the instructions to add the NGINX Management Suite repository.
Add the NGINX Management Suite repository:
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo
RHEL 8: If you’re installing on RHEL 8 and using the distro’s NGINX, run the following commands to use the new version of NGINX (1.20 at the time of this update):
sudo yum module disable nginx:1.14 sudo yum module enable nginx:1.20
Amazon Linux 2
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms-amazon2.repo
Add the NGINX Management Suite repository:
printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nms/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/adm/debian `lsb_release -cs` nginx-plus\n" | sudo tee -a /etc/apt/sources.list.d/nms.list sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx
printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nms/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/adm/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee -a /etc/apt/sources.list.d/nms.list sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx
Install the NGINX Plus metrics module using the appropriate command for your OS:
CentOS, RHEL, RPM-Based
sudo yum update sudo yum install nginx-plus-module-metrics
Debian, Ubuntu, Deb-Based
sudo apt update sudo apt install nginx-plus-module-metrics
To install the NGINX Plus metrics module from NGINX Management Suite, use a command-line tool like
We highly recommend that you encrypt all traffic between NGINX Agent and NGINX Management Suite. You can find instructions in the Encrypt Agent Communications guide.
If your NGINX Management Suite deployment is non-production and doesn’t have valid TLS certificates, you will need to use the tool’s “insecure” option to complete the installation.
In the examples provided, the command shown downloads the package from the NGINX Management Suite host, then runs the installation script.
In the secure example, the
--skip-verify false flag tells NGINX Agent to verify the validity of the certificates used for mTLS.
curl https://<NMS_FQDN>/install/nginx-plus-module-metrics | sudo sh -s -- --skip-verify false
curl --insecure https://<NMS_FQDN>/install/nginx-plus-module-metrics | sudo sh
NGINX Plus advanced metrics are application-centric metrics collected by the NGINX Agent.
To enable advanced metrics, edit the
/etc/nginx-agent/nginx-agent.conf file and add the following directives:
extensions: - advanced-metrics advanced_metrics: socket_path: /var/run/nginx-agent/advanced-metrics.sock aggregation_period: 1s publishing_period: 3s table_sizes_limits: staging_table_max_size: 1000 staging_table_threshold: 1000 priority_table_max_size: 1000 priority_table_threshold: 1000
See the NGINX Agent CLI Flags & Usage topic for a description of each of these flags.
After you install the NGINX Plus metrics module, run the command below to start the NGINX Agent:
sudo systemctl start nginx-agent
After completing the steps in this guide, you will start to see app-centric metrics displayed in the NGINX Management Suite user interface. You can also collect metrics by using the REST API. To learn more, refer to Using the Metrics API.