Mastering Nginx Health Checks: Configuring Reliable Service Monitoring

Service governance requires timely and accurate detection of service node health, automatic registration, and removal of faulty nodes.

Solution Overview

Nginx offers three health‑check schemes for HTTP services:

TCP‑level default check: establishes a TCP connection; success indicates a healthy node.

HTTP‑level default check: sends an HTTP request (GET / HTTP/1.0) and treats 2xx or 3xx responses as healthy.

Custom check: user‑defined logic as described below.

TCP checks cannot verify application readiness or internal congestion, so HTTP checks are often preferred.

Configuration Parameter Details

A typical health‑check configuration looks like this:

check fall=3 interval=3000 rise=2 timeout=2000 type=http;
check_http_expect_alive http_2xx http_3xx ;
check_http_send "GET /checkAlive HTTP/1.0

" ;

check

The check directive accepts the following syntax:

Syntax: check interval=milliseconds [fall=count] [rise=count] [timeout=milliseconds] [default_down=true|false] [type=tcp|http|ssl_hello|mysql|ajp] [port=check_port]
Default: interval=30000 fall=5 rise=2 timeout=1000 default_down=true type=tcp

interval : time between health‑check packets.

fall : number of consecutive failures after which the server is marked down.

rise : number of consecutive successes after which the server is marked up.

timeout : timeout for the health‑check request.

default_down : initial state of the server; true means it starts as down.

type : type of health‑check packet; supported types include tcp, ssl_hello, http, mysql, ajp, and port to specify a custom port.

check_http_expect_alive

Specifies which HTTP response codes are considered successful:

Syntax: check_http_expect_alive [ http_2xx | http_3xx | http_4xx | http_5xx ]
Default: http_2xx | http_3xx

check_http_send

Defines the HTTP request sent during health checks. Using the HEAD method reduces payload; for persistent connections, include a Connection: keep-alive header. When using GET, keep the URI size small to fit within one interval.

Syntax: check_http_send http_packet
Default: "GET / HTTP/1.0

"

Full Example

A complete Nginx configuration with two upstream clusters and health checks:

http {
    upstream cluster1 {
        # simple round-robin
        server 192.168.0.1:80;
        server 192.168.0.2:80;
        check interval=3000 rise=2 fall=5 timeout=1000 type=http;
        check_http_send "HEAD / HTTP/1.0

";
        check_http_expect_alive http_2xx http_3xx;
    }
    upstream cluster2 {
        # simple round-robin
        server 192.168.0.3:80;
        server 192.168.0.4:80;
        check interval=3000 rise=2 fall=5 timeout=1000 type=http;
        check_keepalive_requests 100;
        check_http_send "HEAD / HTTP/1.1
Connection: keep-alive

";
        check_http_expect_alive http_2xx http_3xx;
    }
    server {
        listen 80;
        location /1 {
            proxy_pass http://cluster1;
        }
        location /2 {
            proxy_pass http://cluster2;
        }
        location /status {
            check_status;
            access_log   off;
            allow SOME.IP.ADD.RESS;
            deny all;
        }
    }
}