Module ngx_http_status_module

Example Configuration
Directives
status
status_format
status_zone
Data
Compatibility

The ngx_http_status_module module provides access to various status information.

This module was available as part of our commercial subscription until 1.13.10. It was superseded by the ngx_http_api_module module in 1.13.3.

Example Configuration

http {
    upstream backend {
        zone http_backend 64k;

        server backend1.example.com weight=5;
        server backend2.example.com;
    }

    proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m;

    server {
        server_name backend.example.com;

        location / {
            proxy_pass  http://backend;
            proxy_cache cache_backend;

            health_check;
        }

        status_zone server_backend;
    }

    server {
        listen 127.0.0.1;

        location /upstream_conf {
            upstream_conf;
        }

        location /status {
            status;
        }

        location = /status.html {
        }
    }
}

stream {
    upstream backend {
        zone stream_backend 64k;

        server backend1.example.com:12345 weight=5;
        server backend2.example.com:12345;
    }

    server {
        listen      127.0.0.1:12345;
        proxy_pass  backend;
        status_zone server_backend;
        health_check;
    }
}

Examples of status requests with this configuration:

http://127.0.0.1/status
http://127.0.0.1/status/nginx_version
http://127.0.0.1/status/caches/cache_backend
http://127.0.0.1/status/upstreams
http://127.0.0.1/status/upstreams/backend
http://127.0.0.1/status/upstreams/backend/peers/1
http://127.0.0.1/status/upstreams/backend/peers/1/weight
http://127.0.0.1/status/stream
http://127.0.0.1/status/stream/upstreams
http://127.0.0.1/status/stream/upstreams/backend
http://127.0.0.1/status/stream/upstreams/backend/peers/1
http://127.0.0.1/status/stream/upstreams/backend/peers/1/weight

The simple monitoring page is shipped with this distribution, accessible as “/status.html” in the default configuration. It requires the locations “/status” and “/status.html” to be configured as shown above.

Directives

Syntax:	`status;`
Default:	—
Context:	`location`

The status information will be accessible from the surrounding location. Access to this location should be limited.

Syntax:	`status_format json;` `status_format jsonp [callback];`
Default:	`status_format json;`
Context:	`http`, `server`, `location`

By default, status information is output in the JSON format.

Alternatively, data may be output as JSONP. The callback parameter specifies the name of a callback function. Parameter value can contain variables. If parameter is omitted, or the computed value is an empty string, then “ngx_status_jsonp_callback” is used.

Syntax:	`status_zone zone;`
Default:	—
Context:	`server`

Enables collection of virtual http or stream (1.7.11) server status information in the specified zone. Several servers may share the same zone.

Data

The following status information is provided:

version: Version of the provided data set. The current version is 8.
nginx_version: Version of nginx.
nginx_build: Name of nginx build.
address: The address of the server that accepted status request.
generation: The total number of configuration reloads.
load_timestamp: Time of the last reload of configuration, in milliseconds since Epoch.
timestamp: Current time in milliseconds since Epoch.
pid: The ID of the worker process that handled status request.
ppid: The ID of the master process that started the worker process.
processes: ;; respawned

The total number of abnormally terminated and respawned child processes.

connections: ;; accepted

The total number of accepted client connections.
dropped: The total number of dropped client connections.
active: The current number of active client connections.
idle: The current number of idle client connections.

ssl: ;; handshakes

The total number of successful SSL handshakes.
handshakes_failed: The total number of failed SSL handshakes.
session_reuses: The total number of session reuses during SSL handshake.

requests: ;; total

The total number of client requests.
current: The current number of client requests.

server_zones: For each status_zone: processing The number of client requests that are currently being processed. requests The total number of client requests received from clients. responses total The total number of responses sent to clients. 1xx, 2xx, 3xx, 4xx, 5xx The number of responses with status codes 1xx, 2xx, 3xx, 4xx, and 5xx. discarded The total number of requests completed without sending a response. received The total number of bytes received from clients. sent The total number of bytes sent to clients.
slabs: For each shared memory zone that uses slab allocator: pages used The current number of used memory pages. free The current number of free memory pages. slots For each memory slot size (8, 16, 32, 64, 128, etc.) the following data are provided: used The current number of used memory slots. free The current number of free memory slots. reqs The total number of attempts to allocate memory of specified size. fails The number of unsuccessful attempts to allocate memory of specified size.
upstreams: For each dynamically configurable group, the following data are provided: peers For each server, the following data are provided: id The ID of the server. server An address of the server. name The name of the server specified in the server directive. service The service parameter value of the server directive. backup A boolean value indicating whether the server is a backup server. weight Weight of the server. state Current state, which may be one of “up”, “draining”, “down”, “unavail”, “checking”, or “unhealthy”. active The current number of active connections. max_conns The max_conns limit for the server. requests The total number of client requests forwarded to this server. responses total The total number of responses obtained from this server. 1xx, 2xx, 3xx, 4xx, 5xx The number of responses with status codes 1xx, 2xx, 3xx, 4xx, and 5xx. sent The total number of bytes sent to this server. received The total number of bytes received from this server. fails The total number of unsuccessful attempts to communicate with the server. unavail How many times the server became unavailable for client requests (state “unavail”) due to the number of unsuccessful attempts reaching the max_fails threshold. health_checks checks The total number of health check requests made. fails The number of failed health checks. unhealthy How many times the server became unhealthy (state “unhealthy”). last_passed Boolean indicating if the last health check request was successful and passed tests. downtime Total time the server was in the “unavail”, “checking”, and “unhealthy” states. downstart The time (in milliseconds since Epoch) when the server became “unavail”, “checking”, or “unhealthy”. selected The time (in milliseconds since Epoch) when the server was last selected to process a request (1.7.5). header_time The average time to get the response header from the server (1.7.10). Prior to version 1.11.6, the field was available only when using the least_time load balancing method. response_time The average time to get the full response from the server (1.7.10). Prior to version 1.11.6, the field was available only when using the least_time load balancing method. keepalive The current number of idle keepalive connections. zombies The current number of servers removed from the group but still processing active client requests. zone The name of the shared memory zone that keeps the group’s configuration and run-time state. queue For the requests queue, the following data are provided: size The current number of requests in the queue. max_size The maximum number of requests that can be in the queue at the same time. overflows The total number of requests rejected due to the queue overflow.
caches: For each cache (configured by proxy_cache_path and the likes): size The current size of the cache. max_size The limit on the maximum size of the cache specified in the configuration. cold A boolean value indicating whether the “cache loader” process is still loading data from disk into the cache. hit, stale, updating, revalidated responses The total number of responses read from the cache (hits, or stale responses due to proxy_cache_use_stale and the likes). bytes The total number of bytes read from the cache. miss, expired, bypass responses The total number of responses not taken from the cache (misses, expires, or bypasses due to proxy_cache_bypass and the likes). bytes The total number of bytes read from the proxied server. responses_written The total number of responses written to the cache. bytes_written The total number of bytes written to the cache.
stream: ;; server_zones

For each status_zone

processing The number of client connections that are currently being processed. connections The total number of connections accepted from clients. sessions total The total number of completed client sessions. 2xx, 4xx, 5xx The number of sessions completed with status codes 2xx, 4xx, or 5xx. discarded The total number of connections completed without creating a session. received The total number of bytes received from clients. sent The total number of bytes sent to clients.
upstreams: For each dynamically configurable group, the following data are provided: peers For each server the following data are provided: id The ID of the server. server An address of the server. name The name of the server specified in the server directive. service The service parameter value of the server directive. backup A boolean value indicating whether the server is a backup server. weight Weight of the server. state Current state, which may be one of “up”, “down”, “unavail”, “checking”, or “unhealthy”. active The current number of connections. max_conns The max_conns limit for the server. connections The total number of client connections forwarded to this server. connect_time The average time to connect to the upstream server. Prior to version 1.11.6, the field was available only when using the least_time load balancing method. first_byte_time The average time to receive the first byte of data. Prior to version 1.11.6, the field was available only when using the least_time load balancing method. response_time The average time to receive the last byte of data. Prior to version 1.11.6, the field was available only when using the least_time load balancing method. sent The total number of bytes sent to this server. received The total number of bytes received from this server. fails The total number of unsuccessful attempts to communicate with the server. unavail How many times the server became unavailable for client connections (state “unavail”) due to the number of unsuccessful attempts reaching the max_fails threshold. health_checks checks The total number of health check requests made. fails The number of failed health checks. unhealthy How many times the server became unhealthy (state “unhealthy”). last_passed Boolean indicating if the last health check request was successful and passed tests. downtime Total time the server was in the “unavail”, “checking”, and “unhealthy” states. downstart The time (in milliseconds since Epoch) when the server became “unavail”, “checking”, or “unhealthy”. selected The time (in milliseconds since Epoch) when the server was last selected to process a connection. zombies The current number of servers removed from the group but still processing active client connections. zone The name of the shared memory zone that keeps the group’s configuration and run-time state.

Compatibility

The zone field in http and stream upstreams was added in version 8.
The slabs status data were added in version 8.
The checking state was added in version 8.
The name and service fields in http and stream upstreams were added in version 8.
The nginx_build and ppid fields were added in version 8.
The sessions status data and the discarded field in stream server_zones were added in version 7.
The zombies field was moved from nginx debug version in version 6.
The ssl status data were added in version 6.
The discarded field in server_zones was added in version 6.
The queue status data were added in version 6.
The pid field was added in version 6.
The list of servers in upstreams was moved into peers in version 6.
The keepalive field of an upstream server was removed in version 5.
The stream status data were added in version 5.
The generation field was added in version 5.
The respawned field in processes was added in version 5.
The header_time and response_time fields in upstreams were added in version 5.
The selected field in upstreams was added in version 4.
The draining state in upstreams was added in version 4.
The id and max_conns fields in upstreams were added in version 3.
The revalidated field in caches was added in version 3.
The server_zones, caches, and load_timestamp status data were added in version 2.

© 2002-2021 Igor Sysoev
© 2011-2021 Nginx, Inc.
Licensed under the BSD License.
https://nginx.org/en/docs/http/ngx_http_status_module.html