<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_status_module"
        link="/en/docs/http/ngx_http_status_module.html"
        lang="en"
        rev="6">

<section id="summary">

<para>
The <literal>ngx_http_status_module</literal> module provides
access to various status information.
</para>

<para>
<note>
This module is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
http {
    upstream <emphasis>backend</emphasis> {
        <emphasis>zone</emphasis> http_backend 64k;

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

    proxy_cache_path /data/nginx/cache_backend keys_zone=<emphasis>cache_backend</emphasis>:10m;

    server {
        server_name backend.example.com;

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

            health_check;
        }

        <emphasis>status_zone server_backend;</emphasis>
    }

    server {
        listen 127.0.0.1;

        location /upstream_conf {
            upstream_conf;
        }

        location /status {
            status;
        }

        location = /status.html {
        }
    }
}

stream {
    upstream <emphasis>backend</emphasis> {
        <emphasis>zone</emphasis> 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;
        <emphasis>status_zone server_backend;</emphasis>
        health_check;
    }
}
</example>
</para>

<para>
Examples of status requests with this configuration:
<example>
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/1
http://127.0.0.1/status/upstreams/backend/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/1
http://127.0.0.1/status/stream/upstreams/backend/1/weight
</example>
</para>

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

</section>


<section id="directives" name="Directives">

<directive name="status">
<syntax/>
<default/>
<context>location</context>

<para>
The status information will be accessible from the surrounding location.
</para>

</directive>


<directive name="status_format">
<syntax><literal>json</literal></syntax>
<syntax><literal>jsonp</literal> [<value>callback</value>]</syntax>
<default>json</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
By default, status information is output in the JSON format.
</para>

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

</directive>


<directive name="status_zone">
<syntax><value>zone</value></syntax>
<default/>
<context>server</context>

<para>
Enables collection of virtual
<link doc="ngx_http_core_module.xml" id="server">http</link>
or
<link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link>
(1.7.11) server status information in the specified <value>zone</value>.
Several servers may share the same zone.
</para>

</directive>

</section>


<section id="data" name="Data">

<para>
The following status information is provided:
<list type="tag">

<tag-name id="version"><literal>version</literal></tag-name>
<tag-desc>
Version of the provided data set.
The current version is 5.
</tag-desc>

<tag-name><literal>nginx_version</literal></tag-name>
<tag-desc>
Version of nginx.
</tag-desc>

<tag-name><literal>address</literal></tag-name>
<tag-desc>
The address of the server that accepted status request.
</tag-desc>

<tag-name id="generation"><literal>generation</literal></tag-name>
<tag-desc>
The total number of configuration
<link doc="../control.xml" id="reconfiguration">reloads</link>.
</tag-desc>

<tag-name id="load_timestamp"><literal>load_timestamp</literal></tag-name>
<tag-desc>
Time of the last reload of configuration, in milliseconds since Epoch.
</tag-desc>

<tag-name><literal>timestamp</literal></tag-name>
<tag-desc>
Current time in milliseconds since Epoch.
</tag-desc>

<tag-name id="processes"><literal>processes</literal></tag-name>
<tag-desc>
<list type="tag">

<tag-name id="respawned"><literal>respawned</literal></tag-name>
<tag-desc>
The total number of abnormally terminated and respawned
child processes.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>connections</literal></tag-name>
<tag-desc>
<list type="tag">

<tag-name><literal>accepted</literal></tag-name>
<tag-desc>
The total number of accepted client connections.
</tag-desc>

<tag-name><literal>dropped</literal></tag-name>
<tag-desc>
The total number of dropped client connections.
</tag-desc>

<tag-name><literal>active</literal></tag-name>
<tag-desc>
The current number of active client connections.
</tag-desc>

<tag-name><literal>idle</literal></tag-name>
<tag-desc>
The current number of idle client connections.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>requests</literal></tag-name>
<tag-desc>
<list type="tag">

<tag-name><literal>total</literal></tag-name>
<tag-desc>
The total number of client requests.
</tag-desc>

<tag-name><literal>current</literal></tag-name>
<tag-desc>
The current number of client requests.
</tag-desc>

</list>
</tag-desc>

<tag-name id="server_zones"><literal>server_zones</literal></tag-name>
<tag-desc>
For each <link id="status_zone"/>:
<list type="tag">

<tag-name><literal>processing</literal></tag-name>
<tag-desc>
The number of
client requests that are currently being processed.
</tag-desc>

<tag-name><literal>requests</literal></tag-name>
<tag-desc>
The total number of
client requests received from clients.
</tag-desc>

<tag-name><literal>responses</literal></tag-name>
<tag-desc>
<list type="tag">

<tag-name><literal>total</literal></tag-name>
<tag-desc>
The total number of
responses sent to clients.
</tag-desc>

<tag-name>
<literal>1xx</literal>,
<literal>2xx</literal>,
<literal>3xx</literal>,
<literal>4xx</literal>,
<literal>5xx</literal>
</tag-name>
<tag-desc>
The number of responses with status codes 1xx, 2xx, 3xx, 4xx, and 5xx.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>received</literal></tag-name>
<tag-desc>
The total number of bytes received from clients.
</tag-desc>

<tag-name><literal>sent</literal></tag-name>
<tag-desc>
The total number of bytes sent to clients.
</tag-desc>

</list>
</tag-desc>

<tag-name id="upstreams"><literal>upstreams</literal></tag-name>
<tag-desc>
For each
<link doc="ngx_http_upstream_module.xml" id="server"/>
in the
<link doc="ngx_http_upstream_module.xml" id="zone">dynamically
configurable</link>
<link doc="ngx_http_upstream_module.xml" id="upstream">group</link>,
the following data are provided:
<list type="tag">

<tag-name id="id"><literal>id</literal></tag-name>
<tag-desc>
The ID of the server.
</tag-desc>

<tag-name><literal>server</literal></tag-name>
<tag-desc>
An
<link doc="ngx_http_upstream_module.xml" id="server">address</link>
of the server.
</tag-desc>

<tag-name><literal>backup</literal></tag-name>
<tag-desc>
A boolean value indicating whether the server is a
<link doc="ngx_http_upstream_module.xml" id="backup"/>
server.
</tag-desc>

<tag-name><literal>weight</literal></tag-name>
<tag-desc>
<link doc="ngx_http_upstream_module.xml" id="weight">Weight</link>
of the server.
</tag-desc>

<tag-name id="state"><literal>state</literal></tag-name>
<tag-desc>
Current state, which may be one of
“<literal>up</literal>”,
“<literal>draining</literal>”,
“<literal>down</literal>”,
“<literal>unavail</literal>”,
or
“<literal>unhealthy</literal>”.
</tag-desc>

<tag-name><literal>active</literal></tag-name>
<tag-desc>
The current number of active connections.
</tag-desc>

<!--
<tag-name><literal>keepalive</literal></tag-name>
<tag-desc>
The current number of
idle <link doc="ngx_http_upstream_module.xml" id="keepalive"/> connections.
</tag-desc>
-->

<tag-name id="max_conns"><literal>max_conns</literal></tag-name>
<tag-desc>
The <link doc="ngx_http_upstream_module.xml" id="max_conns"/> limit
for the server.
</tag-desc>

<tag-name><literal>requests</literal></tag-name>
<tag-desc>
The total number of
client requests forwarded to this server.
</tag-desc>

<tag-name><literal>responses</literal></tag-name>
<tag-desc>
<list type="tag">

<tag-name><literal>total</literal></tag-name>
<tag-desc>
The total number of
responses obtained from this server.
</tag-desc>

<tag-name>
<literal>1xx</literal>,
<literal>2xx</literal>,
<literal>3xx</literal>,
<literal>4xx</literal>,
<literal>5xx</literal>
</tag-name>
<tag-desc>
The number of responses with status codes 1xx, 2xx, 3xx, 4xx, and 5xx.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>sent</literal></tag-name>
<tag-desc>
The total number of bytes sent to this server.
</tag-desc>

<tag-name><literal>received</literal></tag-name>
<tag-desc>
The total number of bytes received from this server.
</tag-desc>

<tag-name><literal>fails</literal></tag-name>
<tag-desc>
The total number of
unsuccessful attempts to communicate with the server.
</tag-desc>

<tag-name><literal>unavail</literal></tag-name>
<tag-desc>
How many times
the server became unavailable for client requests
(state “<literal>unavail</literal>”)
due to the number of unsuccessful attempts reaching the
<link doc="ngx_http_upstream_module.xml" id="max_fails"/>
threshold.
</tag-desc>

<tag-name><literal>health_checks</literal></tag-name>
<tag-desc>
<list type="tag">

<tag-name><literal>checks</literal></tag-name>
<tag-desc>
The total number of
<link doc="ngx_http_upstream_module.xml" id="health_check">health check</link>
requests made.
</tag-desc>

<tag-name><literal>fails</literal></tag-name>
<tag-desc>
The number of failed health checks.
</tag-desc>

<tag-name><literal>unhealthy</literal></tag-name>
<tag-desc>
How many times
the server became unhealthy (state “<literal>unhealthy</literal>”).
</tag-desc>

<tag-name><literal>last_passed</literal></tag-name>
<tag-desc>
Boolean indicating
if the last health check request was successful and passed
<link doc="ngx_http_upstream_module.xml" id="match">tests</link>.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>downtime</literal></tag-name>
<tag-desc>
Total time
the server was in the “<literal>unavail</literal>”
and “<literal>unhealthy</literal>” states.
</tag-desc>

<tag-name><literal>downstart</literal></tag-name>
<tag-desc>
The time (in milliseconds since Epoch)
when the server became
“<literal>unavail</literal>”
or “<literal>unhealthy</literal>”.
</tag-desc>

<tag-name id="selected"><literal>selected</literal></tag-name>
<tag-desc>
The time (in milliseconds since Epoch)
when the server was last selected to process a request (1.7.5).
</tag-desc>

<tag-name id="header_time"><literal>header_time</literal></tag-name>
<tag-desc>
The average time to get the
<link doc="ngx_http_upstream_module.xml" id="var_upstream_header_time">response
header</link> from the server (1.7.10).
The field is available when using the
<link doc="ngx_http_upstream_module.xml" id="least_time"/>
load balancing method.
</tag-desc>

<tag-name id="response_time"><literal>response_time</literal></tag-name>
<tag-desc>
The average time to get the
<link doc="ngx_http_upstream_module.xml" id="var_upstream_response_time">full
response</link> from the server (1.7.10).
The field is available when using the
<link doc="ngx_http_upstream_module.xml" id="least_time"/>
load balancing method.
</tag-desc>

</list>
</tag-desc>

<tag-name id="caches"><literal>caches</literal></tag-name>
<tag-desc>
For each cache (configured by
<link doc="ngx_http_proxy_module.xml" id="proxy_cache_path"/> and the likes):
<list type="tag">

<tag-name><literal>size</literal></tag-name>
<tag-desc>
The current size of the cache.
</tag-desc>

<tag-name><literal>max_size</literal></tag-name>
<tag-desc>
The limit on the maximum size of the cache specified in the configuration.
</tag-desc>

<tag-name><literal>cold</literal></tag-name>
<tag-desc>
A boolean value indicating whether the “cache loader” process is still loading
data from disk into the cache.
</tag-desc>

<tag-name>
    <literal>hit</literal>,
    <literal>stale</literal>,
    <literal>updating</literal>,
    <literal>revalidated</literal>
</tag-name>
<tag-desc>
<list type="tag">

<tag-name><literal>responses</literal></tag-name>
<tag-desc>
The total number of responses read from the cache (hits, or stale responses
due to <link doc="ngx_http_proxy_module.xml" id="proxy_cache_use_stale"/>
and the likes).
</tag-desc>

<tag-name><literal>bytes</literal></tag-name>
<tag-desc>
The total number of bytes read from the cache.
</tag-desc>

</list>
</tag-desc>

<tag-name>
    <literal>miss</literal>,
    <literal>expired</literal>,
    <literal>bypass</literal>
</tag-name>
<tag-desc>
<list type="tag">

<tag-name><literal>responses</literal></tag-name>
<tag-desc>
The total number of responses not taken from the cache (misses, expires, or
bypasses due to
<link doc="ngx_http_proxy_module.xml" id="proxy_cache_bypass"/>
and the likes).
</tag-desc>

<tag-name><literal>bytes</literal></tag-name>
<tag-desc>
The total number of bytes read from the proxied server.
</tag-desc>

<tag-name><literal>responses_written</literal></tag-name>
<tag-desc>
The total number of responses written to the cache.
</tag-desc>

<tag-name><literal>bytes_written</literal></tag-name>
<tag-desc>
The total number of bytes written to the cache.
</tag-desc>

</list>
</tag-desc>

</list>
</tag-desc>

<tag-name id="stream"><literal>stream</literal></tag-name>
<tag-desc>

<list type="tag">
<tag-name><literal>server_zones</literal></tag-name>
<tag-desc>
For each <link id="status_zone"/>:
<list type="tag">

<tag-name><literal>processing</literal></tag-name>
<tag-desc>
The number of
client connections that are currently being processed.
</tag-desc>

<tag-name><literal>connections</literal></tag-name>
<tag-desc>
The total number of
connections accepted from clients.
</tag-desc>

<tag-name><literal>received</literal></tag-name>
<tag-desc>
The total number of bytes received from clients.
</tag-desc>

<tag-name><literal>sent</literal></tag-name>
<tag-desc>
The total number of bytes sent to clients.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>upstreams</literal></tag-name>
<tag-desc>
For each
<link doc="../stream/ngx_stream_upstream_module.xml" id="server"/>
in the
<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">dynamically
configurable</link>
<link doc="../stream/ngx_stream_upstream_module.xml" id="upstream">group</link>,
the following data are provided:
<list type="tag">

<tag-name><literal>id</literal></tag-name>
<tag-desc>
The ID of the server.
</tag-desc>

<tag-name><literal>server</literal></tag-name>
<tag-desc>
An
<link doc="../stream/ngx_stream_upstream_module.xml" id="server">address</link>
of the server.
</tag-desc>

<tag-name><literal>backup</literal></tag-name>
<tag-desc>
A boolean value indicating whether the server is a
<link doc="../stream/ngx_stream_upstream_module.xml" id="backup"/>
server.
</tag-desc>

<tag-name><literal>weight</literal></tag-name>
<tag-desc>
<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">Weight</link>
of the server.
</tag-desc>

<tag-name><literal>state</literal></tag-name>
<tag-desc>
Current state, which may be one of
“<literal>up</literal>”,
“<literal>down</literal>”,
“<literal>unavail</literal>”,
or
“<literal>unhealthy</literal>”.
</tag-desc>

<tag-name><literal>active</literal></tag-name>
<tag-desc>
The current number of connections.
</tag-desc>

<tag-name><literal>connections</literal></tag-name>
<tag-desc>
The total number of
client connections forwarded to this server.
</tag-desc>

<tag-name><literal>connect_time</literal></tag-name>
<tag-desc>
The average time to connect to the upstream server.
The field is available when using the
<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/>
load balancing method.
</tag-desc>

<tag-name><literal>first_byte_time</literal></tag-name>
<tag-desc>
The average time to receive the first byte of data.
The field is available when using the
<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/>
load balancing method.
</tag-desc>

<tag-name><literal>response_time</literal></tag-name>
<tag-desc>
The average time to receive the last byte of data.
The field is available when using the
<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/>
load balancing method.
</tag-desc>

<tag-name><literal>sent</literal></tag-name>
<tag-desc>
The total number of bytes sent to this server.
</tag-desc>

<tag-name><literal>received</literal></tag-name>
<tag-desc>
The total number of bytes received from this server.
</tag-desc>

<tag-name><literal>fails</literal></tag-name>
<tag-desc>
The total number of
unsuccessful attempts to communicate with the server.
</tag-desc>

<tag-name><literal>unavail</literal></tag-name>
<tag-desc>
How many times
the server became unavailable for client connections
(state “<literal>unavail</literal>”)
due to the number of unsuccessful attempts reaching the
<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails"/>
threshold.
</tag-desc>

<tag-name><literal>health_checks</literal></tag-name>
<tag-desc>
<list type="tag">

<tag-name><literal>checks</literal></tag-name>
<tag-desc>
The total number of
<link doc="../stream/ngx_stream_upstream_module.xml" id="health_check">health check</link>
requests made.
</tag-desc>

<tag-name><literal>fails</literal></tag-name>
<tag-desc>
The number of failed health checks.
</tag-desc>

<tag-name><literal>unhealthy</literal></tag-name>
<tag-desc>
How many times
the server became unhealthy (state “<literal>unhealthy</literal>”).
</tag-desc>

<tag-name><literal>last_passed</literal></tag-name>
<tag-desc>
Boolean indicating
if the last health check request was successful and passed
<link doc="../stream/ngx_stream_upstream_module.xml" id="match">tests</link>.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>downtime</literal></tag-name>
<tag-desc>
Total time
the server was in the “<literal>unavail</literal>”
and “<literal>unhealthy</literal>” states.
</tag-desc>

<tag-name><literal>downstart</literal></tag-name>
<tag-desc>
The time (in milliseconds since Epoch)
when the server became
“<literal>unavail</literal>”
or “<literal>unhealthy</literal>”.
</tag-desc>

<tag-name><literal>selected</literal></tag-name>
<tag-desc>
The time (in milliseconds since Epoch)
when the server was last selected to process a connection.
</tag-desc>

</list>
</tag-desc>

</list>
</tag-desc>

</list>
</para>

</section>

<section id="compatibility" name="Compatibility">

<para>
<list type="bullet">

<listitem>
The <literal>keepalive</literal> field of an upstream server
was removed in <link id="version"/> 5.
</listitem>

<listitem>
The <link id="stream">stream</link> status data
were added in <link id="version"/> 5.
</listitem>

<listitem>
The
<link id="generation"/> field
was added in <link id="version"/> 5.
</listitem>

<listitem>
The
<link id="respawned"/> field in
<link id="processes"/>
was added in <link id="version"/> 5.
</listitem>

<listitem>
The
<link id="header_time"/> and <link id="response_time"/> fields in
<link id="upstreams"/>
were added in <link id="version"/> 5.
</listitem>

<listitem>
The
<link id="selected"/> field in
<link id="upstreams"/>
was added in <link id="version"/> 4.
</listitem>

<listitem>
The <link id="state">draining</link> state in
<link id="upstreams"/>
was added in <link id="version"/> 4.
</listitem>

<listitem>
The
<link id="id"/> and <link id="max_conns"/> fields in
<link id="upstreams"/>
were added in <link id="version"/> 3.
</listitem>

<listitem>
The <literal>revalidated</literal> field in
<link id="caches"/>
was added in <link id="version"/> 3.
</listitem>

<listitem>
The <link id="server_zones"/>, <link id="caches"/>,
and <link id="load_timestamp"/> status data
were added in <link id="version"/> 2.
</listitem>

</list>
</para>

</section>

</module>