NGINX and NGINX Plus

NGINX is open-source software for web serving, reverse proxying, caching, load balancing, media streaming, and more. It started out as a web server designed for maximum performance and stability. In addition to its HTTP server capabilities, NGINX can also function as a proxy server for email (IMAP, POP3, and SMTP) and a reverse proxy and load balancer for HTTP, TCP, and UDP servers.

NGINX Plus is a software load balancer, web server, and content cache built on top of open source NGINX. NGINX Plus has exclusive enterprise‑grade features beyond what’s available in the open-source offering, including session persistence, configuration via API, and active health checks.

The Sysdig agent has a default configuration to collect metrics for open-source NGINX, provided that you have the HTTP stub status module enabled. NGINX exposes basic metrics about server activity on a simple status page with this status module. If NGINX Plus is installed, a wide range of metrics is available with the NGINX Plus API.

This page describes the setup steps for NGINX/NGINX Plus, the default configuration settings, how to edit the configuration to collect additional information, the metrics available for integration, and sample results in the Sysdig Monitor UI.

NGINX/ NGINX Plus Setup

This section describes the configuration required on the NGINX server.

The Sysdig agent will not collect metrics until the required endpoint is added to the NGINX configuration, per one of the following methods:

• For NGINX (Open Source): use the stub status module

• For NGINX Plus: use the Plus API

Configuration examples of each are provided below

NGINX Stub Status Module Configuration

The ngx_http_stub_status_module provides access to basic status information. It is compiled by default on most distributions. If not, it should be enabled with the --with-http_stub_status_module configuration parameter.

1. To check if the module is already compiled, run the following command:

   nginx -V 2>&1 | grep -o with-http_stub_status_module
   

   If with-http_stub_status_module is listed, the status module is enabled. (For more information, see http://nginx.org/en/docs/http/ngx_http_stub_status_module.html.)

2. Update the NGINX configuration file with /nginx_status endpoint as follows. The default NGINX configuration file is present at /etc/nginx/nginx.conf or /etc/nginx/conf.d/default.conf.

   # HTTP context
   server {
   ...
     # Enable NGINX status module
     location /nginx_status {
       # freely available with open source NGINX
       stub_status;
       access_log   off;
   
       # for open source NGINX < version 1.7.5
       # stub_status on;
     }
   ...
   }
   

NGINX Plus API Configuration

When NGINX Plus is configured, the Plus API can be enabled by adding /api endpoint in the NGINX configuration file as follows.

The default NGINX configuration file is present at /etc/nginx/nginx.conf or /etc/nginx/conf.d/default.conf.

# HTTP context
server {
...
  # Enable NGINX Plus API
  location /api {
    api write=on;
    allow all;
  }
...
}

Sysdig Agent Configuration

• Configuration Examples:

  • Example 1 (Default): When only open-source Nginx is configured.

  • Example 2: When only NginxPlus node is configured.

  • Example 3: When Nginx and NginxPlus are installed in different containers on same host.

• Flag use_plus_api and is used for differentiating NGINX & NGINXPlus metrics.

• NGINXPlus metrics are differentiated with prefix nginx.plus.*

• When use_plus_api = true,

  • nginx_plus_api_url is used to fetch NginxPlus metrics from the NginxPlus node.

  • nginx_status_url is used to fetch Nginx metrics from the Nginx node (If single host is running two separate containers for Nginx and NginxPlus).

Example 1: Default Configuration

With the default configuration, only NGINX metrics will be available once the ngx_http_stub_status_module is configured.

app_checks:
  - name: nginx
    check_module: nginx
    pattern:
      exe: "nginx: worker process"
    conf:
      nginx_status_url: "http://localhost:{port}/nginx_status"
    log_errors: true

Example 2: NGINX Plus only

With this example only NGINX Plus Metrics will be available.

app_checks:
  - name: nginx
    check_module: nginx
    pattern:
      exe: "nginx: worker process"
    conf:
      nginx_plus_api_url: "http://localhost:{port}/api"
      use_plus_api: true
      user: admin
      password: admin
    log_errors: true

Example 3: NGINX and NGINX Plus

This is special case where NGINX open-source and NGINX PLUS are installed on same host but in different containers. With this configuration, respective metrics will be available for NGINX and NGINX Plus containers.

app_checks:
  - name: nginx
    check_module: nginx
    pattern:
      exe: "nginx: worker process"
    conf:
      nginx_plus_api_url: "http://localhost:{port}/api"
      nginx_status_url: "http://localhost:{port}/nginx_status"
      use_plus_api: true
      user: admin
      password: admin
    log_errors: true

List of Metrics

NGINX (Open Source)

See NGINX Metrics.

NGINX Plus

See NGINX Plus Metrics.

Result in the Monitor UI