view xml/en/docs/http/ngx_http_status_module.xml @ 953:aded7086e84f

Commercial version documentation.
author Ruslan Ermilov <ru@nginx.com>
date Thu, 01 Aug 2013 16:31:02 +0400
parents
children fadccc156188
line wrap: on
line source

<?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 module <literal>ngx_http_status_module</literal> 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>
location = /status {
    status;
}
</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>

</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 1.
</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>
An address of the server that accepted status request.
</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>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>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 bytes sent to this server.
</tag-desc>

<tag-name><literal>received</literal></tag-name>
<tag-desc>
The total 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>

</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>
</para>

</section>

</module>