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.

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.

  1. Open an SSH connection to the data plane host and log in.

  2. Run the following command to check whether NGINX Agent is running:

    ps aux | grep nginx-agent
  3. Run the command below to stop NGINX Agent:

    sudo systemctl stop nginx-agent

Install NGINX Plus Metrics Module

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

Add the NGINX Management Suite repository:

  • CentOS/RHEL

    sudo wget -P /etc/yum.repos.d

    • 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

Add the NGINX Management Suite repository:

  • Debian

    printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
    sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx

  • Ubuntu

    printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
    sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx
  1. 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:

  - advanced-metrics
  socket_path: /var/run/nginx-agent/advanced-metrics.sock
  aggregation_period: 1s
  publishing_period: 3s
    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.