Enable metrics

The NGINX One Console dashboard and metrics views present system metrics and detailed NGINX metrics gathered through the NGINX Plus API or the Stub Status API and NGINX access log (for NGINX Open Source).

Enable NGINX Plus Metrics

Enable NGINX Plus API and dashboard

without SSL
with SSL

To collect comprehensive metrics for NGINX Plus, including bytes streamed, information about upstream systems and caches, and counts of all HTTP status codes, add the following to your NGINX Plus configuration file, for example /etc/nginx/nginx.conf or an included file:

nginx# This block enables the NGINX Plus API and dashboard
# For configuration and security recommendations, see:
# https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api
server {
    # Change the listen port if 9000 conflicts
    # (8080 is the conventional API port)
    listen 9000;

    location /api/ {
        # To restrict write methods (POST, PATCH, DELETE), uncomment:
        # limit_except GET {
        #     auth_basic "NGINX Plus API";
        #     auth_basic_user_file /path/to/passwd/file;
        # }

        # Enable API in write mode
        api write=on;

        # To restrict access by network, uncomment the following lines and set your network:
        # allow 192.0.2.0/24;   # replace with your network
        # allow 127.0.0.1/32;   # allow local NGINX Agent to call the NGINX Plus API to retrieve metrics
        # deny  all;
    }

    # Serve the built-in dashboard at /dashboard.html
    location = /dashboard.html {
        root /usr/share/nginx/html;
    }
}

Make sure that the server and location blocks are in the same configuration file, and not split across multiple files using include directives.

By default, all clients can call the API.

To limit who can access the API, uncomment the allow and deny lines under api write=on and replace the example CIDR with your trusted network.

To restrict write methods (POST, PATCH, DELETE), uncomment and configure the limit_except GET block and set up HTTP basic authentication.

For more details, see the NGINX Plus API module documentation and Configuring the NGINX Plus API.

If SSL is enabled on the NGINX Plus API with self-signed certificates like this example:

nginx# This block enables the NGINX Plus API and dashboard with SSL
# For configuration and security recommendations, see:
# https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api
server {
    # Change the listen port if 9000 conflicts
    # (8080 is the conventional API port)
    listen 9000 ssl;
    ssl_certificate /etc/nginx/certs/nginx-selfsigned.crt; 
    ssl_certificate_key /etc/nginx/certs/nginx-selfsigned.key;

    location /api/ {
        # To restrict write methods (POST, PATCH, DELETE), uncomment:
        # limit_except GET {
        #     auth_basic "NGINX Plus API";
        #     auth_basic_user_file /path/to/passwd/file;
        # }

        # Enable API in write mode
        api write=on;

        # To restrict access by network, uncomment the following lines and set your network:
        # allow 192.0.2.0/24;   # replace with your network
        # allow 127.0.0.1/32;   # allow local NGINX Agent to call the NGINX Plus API to retrieve metrics
        # deny  all;
    }

    # Serve the built-in dashboard at /dashboard.html
    location = /dashboard.html {
        root /usr/share/nginx/html;
    }
}

Make sure that the server and location blocks are in the same configuration file, and not split across multiple files using include directives.

To enable NGINX Agent to call the NGINX Plus API, follow the steps below:

Add the following configuration to /etc/nginx-agent/nginx-agent.conf:
data_plane_config:
  nginx:
    api_tls:
      ca: "/etc/nginx/certs/nginx-selfsigned.crt"
Restart NGINX Agent for the configuration changes to take affect
sudo systemctl restart nginx-agent
Run the following command
sudo journalctl -u nginx-agent | grep "NGINX Plus API"
Ensure that the following log message is seen
NGINX Plus API found, NGINX Plus receiver enabled to scrape metrics

Here is an example of how to generate self-signed certificates

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/certs/nginx-selfsigned.key -out /etc/nginx/certs/nginx-selfsigned.crt -subj "/CN=localhost" -addext "subjectAltName=IP:127.0.0.1"

Enable NGINX Plus API and dashboard with Config Sync Groups

To enable the NGINX Plus API and dashboard with Config Sync Groups, add a file named /etc/nginx/conf.d/dashboard.conf to your shared group config. Any instance you add to that group automatically uses those settings.

In the NGINX One Console, select Manage > Config Sync Groups, then pick your config sync group’s name.
Select the Configuration tab, then select Edit Configuration.
Select Add File.
Select New Configuration File.
In the File name box, enter /etc/nginx/conf.d/dashboard.conf, then select Add.
Paste the following into the new file workspace:

without SSL
with SSL

nginx# This block enables the NGINX Plus API and dashboard
# For configuration and security recommendations, see:
# https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api
server {
    # Change the listen port if 9000 conflicts
    # (8080 is the conventional API port)
    listen 9000;

    location /api/ {
        # To restrict write methods (POST, PATCH, DELETE), uncomment:
        # limit_except GET {
        #     auth_basic "NGINX Plus API";
        #     auth_basic_user_file /path/to/passwd/file;
        # }

        # Enable API in write mode
        api write=on;

        # To restrict access by network, uncomment the following lines and set your network:
        # allow 192.0.2.0/24;   # replace with your network
        # allow 127.0.0.1/32;   # allow local NGINX Agent to call the NGINX Plus API to retrieve metrics
        # deny  all;
    }

    # Serve the built-in dashboard at /dashboard.html
    location = /dashboard.html {
        root /usr/share/nginx/html;
    }
}

Make sure that the server and location blocks are in the same configuration file, and not split across multiple files using include directives.

If SSL is enabled on the NGINX Plus API with self-signed certificates like this example:

nginx# This block enables the NGINX Plus API and dashboard with SSL
# For configuration and security recommendations, see:
# https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api
server {
    # Change the listen port if 9000 conflicts
    # (8080 is the conventional API port)
    listen 9000 ssl;
    ssl_certificate /etc/nginx/certs/nginx-selfsigned.crt; 
    ssl_certificate_key /etc/nginx/certs/nginx-selfsigned.key;

    location /api/ {
        # To restrict write methods (POST, PATCH, DELETE), uncomment:
        # limit_except GET {
        #     auth_basic "NGINX Plus API";
        #     auth_basic_user_file /path/to/passwd/file;
        # }

        # Enable API in write mode
        api write=on;

        # To restrict access by network, uncomment the following lines and set your network:
        # allow 192.0.2.0/24;   # replace with your network
        # allow 127.0.0.1/32;   # allow local NGINX Agent to call the NGINX Plus API to retrieve metrics
        # deny  all;
    }

    # Serve the built-in dashboard at /dashboard.html
    location = /dashboard.html {
        root /usr/share/nginx/html;
    }
}

Make sure that the server and location blocks are in the same configuration file, and not split across multiple files using include directives.

To enable NGINX Agent to call the NGINX Plus API, follow the steps below:

Add the following configuration to /etc/nginx-agent/nginx-agent.conf:
data_plane_config:
  nginx:
    api_tls:
      ca: "/etc/nginx/certs/nginx-selfsigned.crt"
Restart NGINX Agent for the configuration changes to take affect
sudo systemctl restart nginx-agent
Run the following command
sudo journalctl -u nginx-agent | grep "NGINX Plus API"
Ensure that the following log message is seen
NGINX Plus API found, NGINX Plus receiver enabled to scrape metrics

Here is an example of how to generate self-signed certificates

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/certs/nginx-selfsigned.key -out /etc/nginx/certs/nginx-selfsigned.crt -subj "/CN=localhost" -addext "subjectAltName=IP:127.0.0.1"

Select Next, review the diff, then select Save and Publish.
Open your browser to http://<instance-ip>:9000/dashboard.html (replace <instance-ip> with the IP or hostname of one of your group members). You should see the NGINX Plus dashboard.

Enable NGINX Plus Metric Collection

To make NGINX Plus metrics available on the NGINX One Console, you must enable shared memory zones for the virtual servers being monitored. Shared memory zones store configuration and runtime state information shared across NGINX worker processes.

To display HTTP and TCP servers in NGINX Console, one or more status_zone directives must be defined. The same zone name can be reused across multiple server blocks.

Since R19, you can apply the status_zone directive to location blocks, allowing statistics to be aggregated separately for servers and locations.

nginxserver {
    # ...
    status_zone status_page;
    location / {
        proxy_pass http://backend;
        status_zone location_zone;
    }
}

After saving the changes, reload NGINX to apply the new configuration:

nginx -s reload

Enable NGINX Open Source Metrics

To collect basic metrics about server activity for NGINX Open Source:

Enable the stub status API

Add the following to your NGINX configuration file:

nginxserver {
   listen 127.0.0.1:8080;
   location /api {
       stub_status;
       allow 127.0.0.1;
       deny all;
   }
}

Make sure that the server and location blocks are in the same configuration file, and not split across multiple files using include directives.

This configuration:

Enables the stub status API endpoint.
Allows requests only from 127.0.0.1 (localhost).
Blocks all other requests for security.

For more details, see the NGINX Stub Status module documentation.

Configure access logging

Enable access logging in your NGINX configuration to collect detailed traffic metrics. Ensure that the following log format is used:

nginxlog_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for" '
'"$bytes_sent" "$request_length" "$request_time" '
'"$gzip_ratio" $server_protocol ';

access_log  /var/log/nginx/access.log  main;

This log format captures key metrics including request timing, response sizes, and client information.

View source

Edit this page

Create a new issue