<?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="1">

<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/> only.
</note>
</para>

</section>


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

<para>
<example>
server {
    location = /status {
        status;
    }

    status_zone example_server;
}
</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 location “<literal>/status</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"/>
status information in the specified <value>zone</value>.
Several virtual 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><literal>version</literal></tag-name>
<tag-desc>
Version of the provided data set.
The current version is 2.
</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><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><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><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><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><literal>server</literal></tag-name>
<tag-desc>
An address of the
<link doc="ngx_http_upstream_module.xml" id="server"/>.
</tag-desc>

<tag-name><literal>backup</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>weight</literal></tag-name>
<tag-desc>
Weight of the
<link doc="ngx_http_upstream_module.xml" id="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 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><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 <literal>max_fails</literal> 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>

</list>
</tag-desc>

<tag-name><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>
Boolean indicating if “cache loader” is still loading data into the cache.
</tag-desc>

<tag-name>
    <literal>hits</literal>,
    <literal>stale</literal>,
    <literal>updating</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>

</list>
</para>

</section>

</module>