NGINX Integration - Atatus Docs

The NGINX integration allows you to monitor your NGINX server with the Atatus Infrastructure Agent. The agent reads metrics from the stub_status endpoint, or from the NGINX Plus API, and picks up the error and access logs from the same configuration file. Use this integration to:

Track request throughput with the total number of client requests.
Monitor connections that are accepted, handled, dropped, and active.
Observe connections in the reading, writing, and waiting states.
Collect NGINX error and access logs.

Setup

The NGINX integration is bundled with the Atatus Infrastructure Agent. The agent polls NGINX over HTTP, so the status endpoint has to be reachable before any metric arrives. Open your NGINX configuration file, usually /etc/nginx/conf.d/default.conf, and check whether the stub_status directive is already present. If it is not, add the following inside the server block:

location /nginx_status {
    stub_status on;
}

Test the configuration after you save the file:

sudo nginx -t

Reload NGINX once the test reports syntax is ok and test is successful:

sudo systemctl reload nginx

Note the port the server block listens on, because the configuration below needs it.

stub_status comes from the ngx_http_stub_status_module, which the official NGINX packages compile in by default. To confirm, run nginx -V and look for --with-http_stub_status_module in the output.

The agent polls the endpoint from the same host, so you can keep it off the public internet by adding allow 127.0.0.1; and deny all; to the location block.

Configuration

Metrics

Copy the NGINX example configuration file that ships with the agent:

cd /etc/atatus-infra-agent/conf.d/nginx.d/
sudo cp nginx.yml.template nginx.yml

Then add the following configuration to /etc/atatus-infra-agent/conf.d/nginx.d/nginx.yml. The first entry is for open source NGINX and the second is for NGINX Plus:

# Metrics section
metrics:
  # ---------------- NORMAL NGINX -----------------------
  - hosts: ["http://127.0.0.1:8080"]
    enabled: true
    metrics_path: /nginx_status
    # Path to server status. Default is nginx_status
    #status_path: "nginx_status"

  # ---------------- NGINX PLUS -------------------------
  - hosts: ["http://127.0.0.1:8080"]
    enabled: false        # <-- set true if using NGINX Plus

    metrics_path: /api

    # NGINX Plus specific
    nginx_plus_option:
      use_plus_api: true
      use_plus_api_stream: true
      only_query_enabled_endpoints: true
      plus_api_version: auto

    # Not using stub_status or VTS
    use_vts: false

    tags:
      - <KEY_1>:<VALUE_1>
      - <KEY_2>:<VALUE_2>

Check these before you save:

The port in hosts must be the port your server block listens on. 8080 is a placeholder, not a default NGINX port.
metrics_path is the location you added during setup. Keep /nginx_status unless you named the location something else. For NGINX Plus it is /api instead.
Enable only the entry that matches your build. Leave enabled: false on the NGINX Plus entry if you run open source NGINX.

The tags list is optional. Replace the placeholders with your own key and value pairs, or remove the list.

Logs

Logs are configured in the same file as metrics. First, turn on log collection for the agent in /etc/atatus-infra-agent/atatus.yml:

logs_enabled: true

Then add a logs section to /etc/atatus-infra-agent/conf.d/nginx.d/nginx.yml. The two default types pick up the standard NGINX log paths:

# Log section
logs:
  - type: error
  - type: access

If your logs are in a different location, replace the two default types with your own paths:

# Log section
logs:
  - type: error
    paths:
      - /var/log/nginx/error.log*
    source: nginx
    service: nginx

  - type: access
    paths:
      - /var/log/nginx/access.log*
    source: nginx
    service: nginx

NGINX Logs Monitoring covers the log options in more detail.

Verify Metrics

You can verify that the status endpoint is reachable by calling it manually:

curl http://127.0.0.1:8080/nginx_status

Replace 8080 with your NGINX port.

Restart the Agent

After configuration, restart the Atatus Infrastructure Agent:

sudo service atatus-infra-agent restart

Metrics

These are the metrics the integration collects from the stub_status endpoint:

Name	Description	Type
nginx.stubstatus.accepts	The total number of accepted client connections.	`long`
nginx.stubstatus.handled	The total number of handled client connections.	`long`
nginx.stubstatus.dropped	The total number of dropped client connections.	`long`
nginx.stubstatus.requests	The total number of client requests.	`long`
nginx.stubstatus.active	The current number of active client connections, including waiting connections.	`long`
nginx.stubstatus.reading	The current number of connections where NGINX is reading the request header.	`long`
nginx.stubstatus.writing	The current number of connections where NGINX is writing the response back to the client.	`long`
nginx.stubstatus.waiting	The current number of idle client connections waiting for a request.	`long`

​Setup

​Configuration

​Metrics

​Logs

​Verify Metrics

​Restart the Agent

​Metrics

Setup

Configuration

Metrics

Logs

Verify Metrics

Restart the Agent

Metrics