Overview: NGINX instance metrics

Overview

F5 NGINX Instance Manager collects two types of data:

  • System metrics: Data about the data plane system, such as CPU and memory usage.
  • Traffic metrics: Data from processed traffic, including NGINX OSS, NGINX Plus, and NGINX logs.

The NGINX Agent collects metrics every 15 seconds and publishes them every 60 seconds.

For a full list of available metrics, see the Metrics Catalog Reference.

How metrics are collected and reported

The NGINX Agent collects metrics every 15 seconds while running on the host. Metrics are then downsampled and sent to the Manager server once per minute.

NGINX Instance Manager stores historical data in an analytics database and applies roll-ups:

  • Data up to 8 days old is stored with 1-minute resolution.
  • Data 8 to 30 days old is stored with 5-minute resolution.
  • Data 30 days to 15 months old is stored with 1-hour resolution.
  • Data older than 15 months is stored with 1-day resolution.

F5 NGINX Plus metrics

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):

# This block:
# - Enables the read-write NGINX Plus API under /api/
# - Serves the built-in dashboard at /dashboard.html
# - Restricts write methods (POST, PATCH, DELETE) to authenticated users
#   and a specified IP range
# Change the listen port if 9000 conflicts; 8080 is the conventional API port.
server {
    # Listen on port 9000 for API and dashboard traffic
    listen 9000 default_server;

    # Handle API calls under /api/
    location /api/ {
        # Enable write operations (POST, PATCH, DELETE)
        api write=on;

        # Allow GET requests from any IP
        allow 0.0.0.0/0;
        # Deny all other requests by default
        deny all;

        # For methods other than GET, require auth and restrict to a network
        limit_except GET {
            # Prompt for credentials with this realm
            auth_basic "NGINX Plus API";
            # Path to the file with usernames and passwords
            auth_basic_user_file /path/to/passwd/file;

            # Allow only this IP range (replace with your own)
            allow 192.0.2.0/24;
            # Deny all other IPs
            deny all;
        }
    }

    # Serve the dashboard page at /dashboard.html
    location = /dashboard.html {
        # Files are located under this directory
        root /usr/share/nginx/html;
    }

    # Redirect any request for / to the dashboard
    location / {
        return 301 /dashboard.html;
    }
}

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

After saving the changes, reload NGINX:

nginx -s reload

NGINX Open Source metrics

To collect basic metrics about server activity for NGINX Open Source, add the following to your NGINX configuration file:

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

This configuration:

  • Enables the stub status API.
  • 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.

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

nginx -s reload

NGINX access log metrics

Enable access logging to collect traffic metrics by parsing logs. Use the following log format:

log_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;

Troubleshooting

System metrics are collected automatically by the NGINX Agent. To collect NGINX-specific metrics, additional configuration is required.