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.

Overview

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.

Before You Begin

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

Supported distributions

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.

Stop NGINX Agent process

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
```

Install NGINX Plus Metrics Module

Install from NGINX Management Suite Package Repository (Recommended)

Select the tab matching your Linux distribution, then follow the instructions to add the NGINX Management Suite repository.

CentOS, RHEL, RPM-Based
Debian, Ubuntu, Deb-Based

Add the NGINX Management Suite repository:

CentOS/RHEL
```
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:

Debian

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

Ubuntu

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
```

Install from NGINX Management Suite

To install the NGINX Plus metrics module from NGINX Management Suite, use a command-line tool like curl or wget.

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.

Secure (recommended):

curl https://<NMS_FQDN>/install/nginx-plus-module-metrics | sudo sh -s -- --skip-verify false

Insecure:

curl --insecure https://<NMS_FQDN>/install/nginx-plus-module-metrics | sudo sh

Configure NGINX Agent to use Advanced Metrics

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 Also:
See the NGINX Agent CLI Flags & Usage topic for a description of each of these flags.

Start NGINX Agent

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.