Module ngx_http_status_module

The ngx_http_status_module module provides access to various status information.

Note

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

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

peers

 - For each [server](http-ngx_http_upstream_module.html#server), the following data are provided: 

id

   - The ID of the server\.

 - `server`

   - An [address](http-ngx_http_upstream_module.html#server) of the server\.

name

   - The name of the server specified in the [server](http-ngx_http_upstream_module.html#server) directive\.

service

   - The [service](http-ngx_http_upstream_module.html#service) parameter value of the [server](http-ngx_http_upstream_module.html#server) directive\.

 - `backup`

   - A boolean value indicating whether the server is a [backup](http-ngx_http_upstream_module.html#backup) server\.

 - `weight`

   - [Weight](http-ngx_http_upstream_module.html#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](http-ngx_http_upstream_module.html#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](http-ngx_http_upstream_module.html#max_fails) threshold\.

 - `health_checks`

   - - `checks`

     - The total number of [health check](http-ngx_http_upstream_hc_module.html#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](http-ngx_http_upstream_hc_module.html#match)\.

 - `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](http-ngx_http_upstream_module.html#var_upstream_header_time) from the server \(1\.7\.10\)\. Prior to version 1\.11\.6, the field was available only when using the [least_time](http-ngx_http_upstream_module.html#least_time) load balancing method\.

response_time

   - The average time to get the [full response](http-ngx_http_upstream_module.html#var_upstream_response_time) from the server \(1\.7\.10\)\. Prior to version 1\.11\.6, the field was available only when using the [least_time](http-ngx_http_upstream_module.html#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](http-ngx_http_upstream_module.html#zone) that keeps the group’s configuration and run\-time state\.

queue

 - For the requests [queue](http-ngx_http_upstream_module.html#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

  • 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](stream-ngx_stream_core_module.html#var_status) 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](stream-ngx_stream_upstream_module.html#zone) [group](stream-ngx_stream_upstream_module.html#upstream), the following data are provided: 
  • peers

     - For each [server](stream-ngx_stream_upstream_module.html#server) the following data are provided: 
    
  • id

       - The ID of the server\.
    
     - `server`
    
       - An [address](stream-ngx_stream_upstream_module.html#server) of the server\.
    

name

     - The name of the server specified in the [server](stream-ngx_stream_upstream_module.html#server) directive\.

service

     - The [service](stream-ngx_stream_upstream_module.html#service) parameter value of the [server](stream-ngx_stream_upstream_module.html#server) directive\.

   - `backup`

     - A boolean value indicating whether the server is a [backup](stream-ngx_stream_upstream_module.html#backup) server\.

   - `weight`

     - [Weight](stream-ngx_stream_upstream_module.html#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](stream-ngx_stream_upstream_module.html#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](stream-ngx_stream_upstream_module.html#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](stream-ngx_stream_upstream_module.html#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](stream-ngx_stream_upstream_module.html#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](stream-ngx_stream_upstream_module.html#max_fails) threshold\.

   - `health_checks`

     - - `checks`

       - The total number of [health check](stream-ngx_stream_upstream_hc_module.html#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](stream-ngx_stream_upstream_hc_module.html#match)\.

   - `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](stream-ngx_stream_upstream_module.html#zone) that keeps the group’s configuration and run\-time state\.

Compatibility