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.
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 status_format |
---|---|
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 |
---|---|
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.