Install NGINX Plus Metrics Module

Follow the steps in this guide to install the NGINX Plus dynamic metrics module and configure the NGINX Agent to push app-centric metrics to NGINX Management Suite.


The NGINX Plus metrics module is a dynamic module 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.


To complete the steps in this tutorial, you need the following:

  • One or more data plane instances 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
  • An installed version of the NGINX Agent on each NGINX Plus instance.

Before You Begin

Stop the NGINX Agent if it’s running.

  1. To see if any NGINX Agent processes are running, run the following command:

    ps aux | grep nginx-agent
  2. Stop the NGINX Agent:

    sudo systemctl stop nginx-agent

Install NGINX Plus Metrics Module

Choose one of the following installation methods to install the NGINX Plus Module Metrics on your data plane host:

Install from NGINX Management Suite Repo

Add NGINX Management Suite Repo

  1. Add the NGINX Management Suite repository:

    • CentOS, RHEL, RPM-Based

      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
    • Debian

      printf "deb `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 `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
  2. Add the NGINX Signing Key to the repository:

    • CentOS, RHEL, RPM-Based

      curl -o /tmp/nginx_signing.key
      sudo rpmkeys --import /tmp/nginx_signing.key
    • Debian, Ubuntu, Deb-Based

      wget -O /tmp/nginx_signing.key
      sudo apt-key add /tmp/nginx_signing.key

Install NGINX Plus Metrics Module

  • CentOS, RHEL, RPM-Based

    yum install nginx-plus-module-metrics
  • Debian, Ubuntu, Deb-Based

    apt install nginx-plus-module-metrics

Install via Instance Manager API Gateway

Install NGINX Plus Metrics Module

You can install the NGINX Plus metrics module using curl, wget, or any command-line tool for transferring data with URLs. If the NGINX Management Suite isn’t set up with valid TLS certificates, you can use the available insecure flags of those tools. See the following examples:

  • Secure:

    curl https://<NGINX-MANAGEMENT-SUITE-FQDN>/install/nginx-plus-module-metrics | sudo sh -s -- --skip-verify false
  • Insecure:

    curl -k https://<NGINX-MANAGEMENT-SUITE-FQDN>/install/nginx-plus-module-metrics | sudo sh

Enable NGINX Plus 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:

  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

To start the NGINX Agent, run the following command:

sudo systemctl start nginx-agent