Nginx

Auto-Detection

Health Check

Built-in Metrics

Logs

Tutorial availableMonitoring Nginx web server with Bleemeo

Read the tutorial

Nginx is a high-performance web server, reverse proxy, and load balancer.

Auto-Detection

Glouton detects Nginx by its process and listening port (default: 80).

To enable metrics gathering, ensure Glouton can access the Nginx status page at http://server-address/nginx_status. Add the following to your site definition (e.g. /etc/nginx/sites-enabled/default):

location /nginx_status {
    stub_status on;
}

If your Nginx build does not include stub_status, see the ngx_http_stub_status_module documentation.

When using Docker, you can set http_path and http_host via labels:

docker run --label glouton.http_path="/readiness" --label glouton.http_host="my-host" [...]

If auto-detected parameters are incorrect, override them manually:

Linux

sudo tee /etc/glouton/conf.d/99-nginx.conf > /dev/null << 'EOF'
service:
  # For an Nginx running outside a container
  - type: "nginx"
    address: "127.0.0.1"
    port: 80   # HTTP listener, agent does not support HTTPS here
    http_path: "/"   # Path used for availability check, not metrics gathering
    http_host: "127.0.0.1:80"   # Host header sent

  # For an additional Nginx running outside a container
  - type: "nginx"
    instance: "NAME_ASSOCIATED_WITH_YOUR_ADDITIONAL_SERVICE"
    address: "127.0.0.1"
    port: 81
    http_path: "/"
    http_host: "127.0.0.1:81"

  # For an Nginx running in a Docker container
  - type: "nginx"
    instance: "CONTAINER_NAME"
    address: "172.17.0.2"
    port: 80
    http_path: "/"
    http_host: "127.0.0.1:80"
EOF

Windows

Create or edit C:\ProgramData\glouton\conf.d\99-nginx.conf:

service:
  # For an Nginx running outside a container
  - type: "nginx"
    address: "127.0.0.1"
    port: 80   # HTTP listener, agent does not support HTTPS here
    http_path: "/"   # Path used for availability check, not metrics gathering
    http_host: "127.0.0.1:80"   # Host header sent

  # For an additional Nginx running outside a container
  - type: "nginx"
    instance: "NAME_ASSOCIATED_WITH_YOUR_ADDITIONAL_SERVICE"
    address: "127.0.0.1"
    port: 81
    http_path: "/"
    http_host: "127.0.0.1:81"

Glouton automatically detects configuration changes.

Service Check

Glouton performs an HTTP check on the configured port and path to verify that Nginx is responding.

Built-in Metrics

Metric	Description
service_status	Status of Nginx
nginx_requests	Number of requests per second
nginx_connections_accepted	Number of client connections established per second
nginx_connections_handled	Number of client connections processed per second
nginx_connections_active	Number of active client connections to Nginx
nginx_connections_waiting	Number of idle client connections waiting for a request
nginx_connections_reading	Number of connections where Nginx is reading the request header
nginx_connections_writing	Number of connections where Nginx is writing the response

Logs

Glouton collects Nginx access and error logs for analysis in Bleemeo.

Monitoring Troubleshooting

See Troubleshoot a Service Check or Missing Metrics for what applies to every service: finding the address and port Glouton really uses, what each check message means, and how to read the collection error — which does not appear in the agent logs at the default level.

The check and the metrics use two different URLs, which is what makes Nginx confusing to debug:

	URL	Configurable
Service check	http://<address>:<port>/	Yes, with http_path and http_host
Metrics	http://<address>:<port>/nginx_status	No — the path is fixed

The Service Check is not OK

The check is an HTTP request, so its status text carries the HTTP code:

Status text	Cause	Fix
HTTP WARN - http_code=404	Nginx serves nothing at / — typically name-based virtual hosts, where the default server has no root	Point the check at a path that exists with http_path, and set http_host to the virtual host name
HTTP WARN - http_code=403	An allow/deny rule, or a directory listing refused	Use a http_path the agent is allowed to fetch
HTTP CRITICAL - http_code=502 or 503	Nginx is healthy but the application behind it is not	Set http_path to a static path served by Nginx itself, so the check measures Nginx
HTTP connection failed: ...	Nothing listening on that port, or the listener is HTTPS-only	The check speaks plain HTTP: point it at the HTTP listener, or use an uptime monitor for an HTTPS endpoint
Connection timed out after 10 seconds	A firewall drops the packets, or all workers are busy	Open the port, or investigate the saturation

Metrics are Missing

A passing check says nothing about the metrics: they are collected separately.

Metrics come from stub_status, which Glouton fetches at the fixed path /nginx_status on the same address and port. http_path does not move it.

Check the endpoint from the machine where the agent runs:

curl -i http://127.0.0.1/nginx_status

It must return the Active connections: block.

What the endpoint returns	Cause	Fix
404	stub_status not enabled	Add the location /nginx_status block shown above
404	Enabled on another path or another server block	Add it to the server block that listens on the port Glouton uses
403	Access restricted	Allow the agent address in that location
a connection error	The listener is HTTPS-only	Metrics need a plain HTTP listener; expose stub_status on one, even on 127.0.0.1 only
404, and nginx -V does not list --with-http_stub_status_module	Nginx built without the module	Install a build that includes it