<?xml version="1.0"?>

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

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

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

<section id="summary">

<para>
The <literal>ngx_http_stub_status_module</literal> module provides
access to basic status information.
</para>

<para>
This module is not built by default, it should be enabled with the
<literal>--with-http_stub_status_module</literal>
configuration parameter.
</para>

</section>


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

<para>
<example>
location = /basic_status {
    stub_status;
}
</example>
This configuration creates a simple web page
with basic status data which may look like as follows:
<example>
Active connections: 291
server accepts handled requests
 16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106
</example>
</para>

</section>


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

<directive name="stub_status">
<syntax/>
<default/>
<context>server</context>
<context>location</context>

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

<para>
<note>
In versions prior to 1.7.5,
the directive syntax required an arbitrary argument, for example,
“<literal>stub_status on</literal>”.
</note>
</para>

</directive>

</section>


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

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

<tag-name id="stubstat_active"><literal>Active connections</literal></tag-name>
<tag-desc>
The current number of active client connections
including <literal>Waiting</literal> connections.
</tag-desc>

<tag-name id="stubstat_accepts"><literal>accepts</literal></tag-name>
<tag-desc>
The total number of accepted client connections.
</tag-desc>

<tag-name id="stubstat_handled"><literal>handled</literal></tag-name>
<tag-desc>
The total number of handled connections.
Generally, the parameter value is the same as <literal>accepts</literal>
unless some resource limits have been reached
(for example, the
<link doc="../ngx_core_module.xml" id="worker_connections"/> limit).
</tag-desc>

<tag-name id="stubstat_requests"><literal>requests</literal></tag-name>
<tag-desc>
The total number of client requests.
</tag-desc>

<tag-name id="stubstat_reading"><literal>Reading</literal></tag-name>
<tag-desc>
The current number of connections where nginx is reading the request header.
</tag-desc>

<tag-name id="stubstat_writing"><literal>Writing</literal></tag-name>
<tag-desc>
The current number of connections
where nginx is writing the response back to the client.
</tag-desc>

<tag-name id="stubstat_waiting"><literal>Waiting</literal></tag-name>
<tag-desc>
The current number of idle client connections waiting for a request.
</tag-desc>

</list>
</para>

</section>


<section id="variables" name="Embedded Variables">

<para>
The <literal>ngx_http_stub_status_module</literal> module
supports the following embedded variables (1.3.14):
<list type="tag">

<tag-name
id="var_connections_active"><var>$connections_active</var></tag-name>
<tag-desc>
same as the <literal>Active connections</literal> value;
</tag-desc>

<tag-name
id="var_connections_reading"><var>$connections_reading</var></tag-name>
<tag-desc>
same as the <literal>Reading</literal> value;
</tag-desc>

<tag-name
id="var_connections_writing"><var>$connections_writing</var></tag-name>
<tag-desc>
same as the <literal>Writing</literal> value;
</tag-desc>

<tag-name
id="var_connections_waiting"><var>$connections_waiting</var></tag-name>
<tag-desc>
same as the <literal>Waiting</literal> value.
</tag-desc>

</list>
</para>

</section>

</module>