Nginx Integration

The Nginx collector monitors Nginx web server instances by scraping the stub_status module endpoint, collecting connection and request metrics. It also detects and reports the Nginx server version (e.g., "nginx/1.27.4") via the VersionReporter interface.

Setup

1. Enable stub_status

Add a stub_status location to your Nginx config. Restrict access to localhost only:

server {
    listen 127.0.0.1:80;
    server_name localhost;

    location /nginx_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}

Reload Nginx:

nginx -t && nginx -s reload

Verify the endpoint returns data:

curl http://127.0.0.1/nginx_status
# Active connections: 291
# server accepts handled requests
#  16630948 16630948 31070465
# Reading: 6 Writing: 179 Waiting: 106

2. Configure the agent

Add an Nginx collector to the agent's config.yaml:

collectors:
  - type: nginx
    name: nginx-main
    url: "http://127.0.0.1/nginx_status"

Field	Required	Description
type	Yes	Must be nginx
name	No	Unique name for this collector instance (defaults to nginx)
url	Yes	URL of the stub_status endpoint

You can monitor multiple Nginx instances by adding multiple collectors with different names:

collectors:
  - type: nginx
    name: nginx-frontend
    url: "http://127.0.0.1/nginx_status"
  - type: nginx
    name: nginx-api
    url: "http://127.0.0.1:8081/status"

Metrics collected

The Nginx collector reports the following metrics under the nginx_ prefix:

Metric	Type	Description
nginx_connections_active	Gauge	Current number of active connections (including waiting)
nginx_connections_accepted_total	Counter	Total accepted client connections
nginx_connections_handled_total	Counter	Total handled connections (normally equals accepted)
nginx_requests_total	Counter	Total HTTP requests served
nginx_connections_reading	Gauge	Connections currently reading the request header
nginx_connections_writing	Gauge	Connections currently writing a response back to the client
nginx_connections_waiting	Gauge	Idle keep-alive connections waiting for a request

Counter metrics (nginx_connections_accepted_total, nginx_connections_handled_total, nginx_requests_total) are stored as raw cumulative values. Use the derivative=true query parameter to get per-second rates.

tip

The relationship between these metrics: active = reading + writing + waiting. If accepted != handled, Nginx is dropping connections (resource limit reached).

Configuration collected

The Nginx collector also implements CollectConfig(), which runs nginx -T to capture the full resolved configuration. Key tuning parameters, virtual host information, reverse proxy topology, and SSL certificate details are extracted and displayed in the Config tab of the Integration Detail Page. Config is refreshed every 5 minutes.

note

The agent must have permission to run nginx -T. If Nginx is managed by root, ensure the agent user has the necessary sudo privileges or run the agent as root.

Directives

Parameter	Category	Description
worker_processes	Nginx / Server	Number of worker processes (e.g. auto, 4)
worker_connections	Nginx / Server	Max simultaneous connections per worker
sendfile	Nginx / Server	Whether sendfile is enabled for efficient file transfer
tcp_nopush	Nginx / Server	Whether TCP_NOPUSH socket option is enabled
server_names_hash_bucket_size	Nginx / Server	Hash bucket size for server names
keepalive_timeout	Nginx / HTTP	Timeout for keep-alive connections
client_max_body_size	Nginx / HTTP	Max allowed request body size
gzip	Nginx / HTTP	Whether gzip compression is enabled
proxy_connect_timeout	Nginx / HTTP	Timeout for establishing proxy connections
proxy_read_timeout	Nginx / HTTP	Timeout for reading proxy responses
ssl_protocols	Nginx / SSL	Allowed SSL/TLS protocol versions
access_log	Nginx / Logging	Access log path and format
error_log	Nginx / Logging	Error log path and level

Computed values

Parameter	Category	Description
server_count	Virtual Hosts	Total number of server {} blocks
server_names	Virtual Hosts	Comma-separated list of active domain names (excludes _ and localhost)
upstreams	Virtual Hosts	Reverse proxy topology: server_name → proxy_pass target mappings, sorted
upstream_backends	Load Balancing	Upstream block definitions: name(server1, server2) entries, sorted
ssl_certificates	SSL / TLS	SSL cert paths with expiry: domain → /path/to/cert.pem (expires YYYY-MM-DD)
ssl_cert_earliest_expiry	SSL / TLS	Earliest SSL certificate expiry date across all certs (useful for alerting)

tip

The ssl_cert_earliest_expiry value is useful for monitoring certificate renewals. If this date is approaching, renew the certificate before it expires to avoid service disruptions.

info

Server blocks are detected at any brace depth, so configurations using include directives (e.g. sites-enabled/*) that produce flattened output from nginx -T are correctly parsed.

Frontend rendering

The Config tab renders these values with structured formatting instead of plain comma-separated text:

• server_names — Each domain name displayed as an individual badge
• upstreams — Arrow-separated pairs (server_name → proxy_pass target), one per line
• upstream_backends — Grouped display with the upstream name as a header and backend servers listed below
• ssl_certificates — Cards with the server name, certificate path, and a color-coded expiry badge (red if expired, amber if ≤30 days, green if >30 days)
• ssl_cert_earliest_expiry — A standalone color-coded expiry badge

Version Detection

The collector parses the "nginx version: nginx/X.Y.Z" line from a separate nginx -v invocation run during config collection (nginx -T does not include the version line). The version is reported via the VersionReporter interface and displayed as a version badge next to the collector name on both the Integration Detail Page and the Host Detail Page (Integrations tab).

Dashboard

The Integration Detail Page for Nginx includes a Metrics tab with a dedicated dashboard driven by the backend's generic integration metrics API. Since the frontend renders integration dashboards dynamically from the integration catalog, no frontend code changes are needed.

Key metrics to watch:

• Active Connections -- current nginx_connections_active; sustained high values may indicate connection pooling issues or slow backends
• Request Rate -- nginx_requests_total (derivative); sharp drops may indicate upstream failures
• Waiting Connections -- nginx_connections_waiting; high values are normal for keep-alive configurations

When multiple Nginx collectors exist on a host, a collector picker lets you switch between instances.

Troubleshooting

Connection refused

status: error
status_message: "stub_status request: Get \"http://127.0.0.1/nginx_status\": dial tcp 127.0.0.1:80: connect: connection refused"

• Verify Nginx is running: systemctl status nginx
• Check the stub_status URL matches the Nginx config
• Ensure the port is correct

HTTP 403 Forbidden

status: error
status_message: "stub_status returned HTTP 403"

• The stub_status location has allow/deny rules blocking the agent
• Add allow 127.0.0.1; to the stub_status location block

HTTP 404 Not Found

status: error
status_message: "stub_status returned HTTP 404"

• The stub_status module is not enabled or the URL path is wrong
• Check that ngx_http_stub_status_module is compiled into Nginx: nginx -V 2>&1 | grep stub_status
• Verify the location path matches the configured url

Checking status

View the collector status in the Proxima Console UI:

1. Navigate to Integrations to see all hosts and their status
2. Click on the Nginx integration to view the detail page
3. Or go to a specific Host and check the Integrations tab for per-host status
4. Green = ok, Red = error, Gray = unknown