<?xml version="1.0"?>

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

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

<module name="Модуль ngx_http_status_module"
        link="/ru/docs/http/ngx_http_status_module.html"
        lang="ru"
        rev="5">

<section id="summary">

<para>
Модуль <literal>ngx_http_status_module</literal> предоставляет
доступ к информации о состоянии сервера.
</para>

<para>
<note>
Модуль доступен как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
upstream <emphasis>backend</emphasis> {
    <emphasis>zone</emphasis> upstream_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 {
    }
}
</example>
</para>

<para>
Примеры запросов информации о состоянии,
возможные с данной конфигурацией:
<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
</example>
</para>

<para>
В составе дистрибутива nginx имеется простая страница мониторинга, доступная
по запросу “<literal>/status.html</literal>” в стандартной конфигурации.
Для работы этой страницы требуется настроить location
“<literal>/status</literal>” и location “<literal>/status.html</literal>”
как показано выше.
</para>

</section>


<section id="directives" name="Директивы">

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

<para>
Информация о состоянии будет доступна из содержащего 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>
По умолчанию информация выводится в формате JSON.
</para>

<para>
Также данные могут выводиться в формате JSONP.
Параметр <value>callback</value> задаёт имя callback-функции.
Значение может содержать переменные.
Если параметр не задан или вычисленное значение является пустой строкой,
используется имя “<literal>ngx_status_jsonp_callback</literal>”.
</para>

</directive>


<directive name="status_zone">
<syntax><value>зона</value></syntax>
<default/>
<context>server</context>

<para>
Включает сбор информации о состоянии виртуального
<link doc="ngx_http_core_module.xml" id="server">сервера</link>
в указанной <value>зоне</value>.
В одной и той же зоне может одновременно собираться информация
сразу по нескольким виртуальным серверам.
</para>

</directive>

</section>


<section id="data" name="Данные">

<para>
Доступна следующая информация:
<list type="tag">

<tag-name id="version"><literal>version</literal></tag-name>
<tag-desc>
Версия предоставляемого набора данных.
Текущей является версия 5.
</tag-desc>

<tag-name><literal>nginx_version</literal></tag-name>
<tag-desc>
Версия nginx.
</tag-desc>

<tag-name><literal>address</literal></tag-name>
<tag-desc>
Адрес сервера, принявшего запрос получения информации о состоянии.
</tag-desc>

<tag-name id="generation"><literal>generation</literal></tag-name>
<tag-desc>
Суммарное число
<link doc="../control.xml" id="reconfiguration">перезагрузок</link>
конфигурации.
</tag-desc>

<tag-name id="load_timestamp"><literal>load_timestamp</literal></tag-name>
<tag-desc>
Время последней перезагрузки конфигурации, в миллисекундах с начала эпохи.
</tag-desc>

<tag-name><literal>timestamp</literal></tag-name>
<tag-desc>
Текущее время в миллисекундах с начала эпохи.
</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>
Суммарное число перезапусков аварийно завершённых
дочерних процессов.
</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>
Суммарное число принятых клиентских соединений.
</tag-desc>

<tag-name><literal>dropped</literal></tag-name>
<tag-desc>
Суммарное число отвергнутых клиентских соединений.
</tag-desc>

<tag-name><literal>active</literal></tag-name>
<tag-desc>
Текущее число активных клиентских соединений.
</tag-desc>

<tag-name><literal>idle</literal></tag-name>
<tag-desc>
Текущее число бездействующих клиентских соединений.
</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>
Суммарное число клиентских запросов.
</tag-desc>

<tag-name><literal>current</literal></tag-name>
<tag-desc>
Текущее число клиентских запросов.
</tag-desc>

</list>
</tag-desc>

<tag-name id="server_zones"><literal>server_zones</literal></tag-name>
<tag-desc>
Для каждой <link id="status_zone"/>:
<list type="tag">

<tag-name><literal>processing</literal></tag-name>
<tag-desc>
Число обрабатываемых в настоящий момент
клиентских запросов.
</tag-desc>

<tag-name><literal>requests</literal></tag-name>
<tag-desc>
Суммарное число
запросов, полученных от клиентов.
</tag-desc>

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

<tag-name><literal>total</literal></tag-name>
<tag-desc>
Суммарное число
ответов, отправленных клиентам.
</tag-desc>

<tag-name>
<literal>1xx</literal>,
<literal>2xx</literal>,
<literal>3xx</literal>,
<literal>4xx</literal>,
<literal>5xx</literal>
</tag-name>
<tag-desc>
Число ответов со статусами 1xx, 2xx, 3xx, 4xx и 5xx.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>received</literal></tag-name>
<tag-desc>
Суммарное число байт, полученных от клиентов.
</tag-desc>

<tag-name><literal>sent</literal></tag-name>
<tag-desc>
Суммарное число байт, отправленных клиентам.
</tag-desc>

</list>
</tag-desc>

<tag-name id="upstreams"><literal>upstreams</literal></tag-name>
<tag-desc>
Для каждого
<link doc="ngx_http_upstream_module.xml" id="server">сервера</link>
в
<link doc="ngx_http_upstream_module.xml" id="zone">динамически
настраиваемой</link>
<link doc="ngx_http_upstream_module.xml" id="upstream">группе</link>
доступны следующие данные:
<list type="tag">

<tag-name id="id"><literal>id</literal></tag-name>
<tag-desc>
Идентификатор сервера.
</tag-desc>

<tag-name><literal>server</literal></tag-name>
<tag-desc>
<link doc="ngx_http_upstream_module.xml" id="server">Адрес</link>
сервера.
</tag-desc>

<tag-name><literal>backup</literal></tag-name>
<tag-desc>
Логическое значение, означающее, является ли сервер
<link doc="ngx_http_upstream_module.xml" id="backup">запасным</link>.
</tag-desc>

<tag-name><literal>weight</literal></tag-name>
<tag-desc>
<link doc="ngx_http_upstream_module.xml" id="weight">Вес</link>
сервера.
</tag-desc>

<tag-name id="state"><literal>state</literal></tag-name>
<tag-desc>
Текущее состояние, которое может быть одним из
“<literal>up</literal>”,
“<literal>draining</literal>”,
“<literal>down</literal>”,
“<literal>unavail</literal>”
или
“<literal>unhealthy</literal>”.
</tag-desc>

<tag-name><literal>active</literal></tag-name>
<tag-desc>
Текущее число активных соединений.
</tag-desc>

<!--
<tag-name><literal>keepalive</literal></tag-name>
<tag-desc>
Текущее число бездействующих
<link doc="ngx_http_upstream_module.xml" id="keepalive"/>-соединений.
</tag-desc>
-->

<tag-name id="max_conns"><literal>max_conns</literal></tag-name>
<tag-desc>
Ограничение <link doc="ngx_http_upstream_module.xml" id="max_conns"/>
для сервера.
</tag-desc>

<tag-name><literal>requests</literal></tag-name>
<tag-desc>
Суммарное число
клиентских запросов, перенаправленных на этот сервер.
</tag-desc>

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

<tag-name><literal>total</literal></tag-name>
<tag-desc>
Суммарное число
ответов, полученных от этого сервера.
</tag-desc>

<tag-name>
<literal>1xx</literal>,
<literal>2xx</literal>,
<literal>3xx</literal>,
<literal>4xx</literal>,
<literal>5xx</literal>
</tag-name>
<tag-desc>
Число ответов со статусами 1xx, 2xx, 3xx, 4xx и 5xx.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>sent</literal></tag-name>
<tag-desc>
Суммарное число байт, отправленных на этот сервер.
</tag-desc>

<tag-name><literal>received</literal></tag-name>
<tag-desc>
Суммарное число байт, полученных с этого сервера.
</tag-desc>

<tag-name><literal>fails</literal></tag-name>
<tag-desc>
Суммарное число
неудачных попыток работы с этим сервером.
</tag-desc>

<tag-name><literal>unavail</literal></tag-name>
<tag-desc>
Количество раз, когда
сервер становился недоступным для клиентских запросов
(состояние “<literal>unavail</literal>”)
из-за достижения порогового числа неудачных попыток
<link doc="ngx_http_upstream_module.xml" id="max_fails"/>.
</tag-desc>

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

<tag-name><literal>checks</literal></tag-name>
<tag-desc>
Суммарное число запросов
<link doc="ngx_http_upstream_module.xml" id="health_check">проверки
работоспособности</link>.
</tag-desc>

<tag-name><literal>fails</literal></tag-name>
<tag-desc>
Число неудачных проверок работоспособности.
</tag-desc>

<tag-name><literal>unhealthy</literal></tag-name>
<tag-desc>
Количество раз, когда
сервер становился неработоспособным (состояние “<literal>unhealthy</literal>”).
</tag-desc>

<tag-name><literal>last_passed</literal></tag-name>
<tag-desc>
Логическое значение, означающее, была ли последняя проверка
работоспособности удачной и удовлетворял ли ответ заданным
<link doc="ngx_http_upstream_module.xml" id="match">тестам</link>.
</tag-desc>

</list>
</tag-desc>

<tag-name><literal>downtime</literal></tag-name>
<tag-desc>
Суммарное время,
когда сервер находился в состояниях “<literal>unavail</literal>”
и “<literal>unhealthy</literal>”.
</tag-desc>

<tag-name><literal>downstart</literal></tag-name>
<tag-desc>
Время (в миллисекундах с начала эпохи),
когда сервер стал
“<literal>unavail</literal>”
или “<literal>unhealthy</literal>”.
</tag-desc>

<tag-name id="selected"><literal>selected</literal></tag-name>
<tag-desc>
Время (в миллисекундах с начала эпохи),
когда сервер в последний раз был выбран для обработки запроса (1.7.5).
</tag-desc>

<tag-name id="header_time"><literal>header_time</literal></tag-name>
<tag-desc>
Среднее время получения
<link doc="ngx_http_upstream_module.xml" id="var_upstream_header_time">заголовка
ответа</link> от сервера (1.7.10).
Поле доступно при использовании метода балансировки
<link doc="ngx_http_upstream_module.xml" id="least_time"/>.
</tag-desc>

<tag-name id="response_time"><literal>response_time</literal></tag-name>
<tag-desc>
Среднее время получения
<link doc="ngx_http_upstream_module.xml" id="var_upstream_response_time">всего
ответа</link> от сервера (1.7.10).
Поле доступно при использовании метода балансировки
<link doc="ngx_http_upstream_module.xml" id="least_time"/>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="caches"><literal>caches</literal></tag-name>
<tag-desc>
Для каждого кэша, сконфигурированного при помощи
<link doc="ngx_http_proxy_module.xml" id="proxy_cache_path"/>
и аналогичных директив:
<list type="tag">

<tag-name><literal>size</literal></tag-name>
<tag-desc>
Текущий размер кэша.
</tag-desc>

<tag-name><literal>max_size</literal></tag-name>
<tag-desc>
Ограничение на максимальный размер кэша, заданное в конфигурации.
</tag-desc>

<tag-name><literal>cold</literal></tag-name>
<tag-desc>
Логическое значение, указывающее, продолжается ли загрузка
данных процессом “cache loader” с диска в кэш.
</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>
Суммарное число ответов, прочитанных из кэша (попадания в кэш
или просроченные ответы вследствие
<link doc="ngx_http_proxy_module.xml" id="proxy_cache_use_stale"/>
и аналогичных директив).
</tag-desc>

<tag-name><literal>bytes</literal></tag-name>
<tag-desc>
Суммарное число байт, прочитанных из кэша.
</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>
Суммарное число ответов, взятых не из кэша (<literal>miss</literal> —
отсутствие данных в кэше, <literal>expired</literal> — просроченные ответы,
<literal>bypass</literal> — ответ не был взят из кэша
вследствие <link doc="ngx_http_proxy_module.xml" id="proxy_cache_bypass"/>
и аналогичных директив).
</tag-desc>

<tag-name><literal>bytes</literal></tag-name>
<tag-desc>
Суммарное число байт, прочитанных с проксируемого сервера.
</tag-desc>

<tag-name><literal>responses_written</literal></tag-name>
<tag-desc>
Суммарное число ответов, записанных в кэш.
</tag-desc>

<tag-name><literal>bytes_written</literal></tag-name>
<tag-desc>
Суммарное число байт, записанных в кэш.
</tag-desc>

</list>
</tag-desc>

</list>
</tag-desc>

</list>
</para>

</section>

<section id="compatibility" name="Совместимость">

<para>
<list type="bullet">

<listitem>
Поле <literal>keepalive</literal> сервера группы
было удалено в <link id="version">версии</link> 5.
</listitem>

<listitem>
Поле <link id="generation"/>
было добавлено в <link id="version">версии</link> 5.
</listitem>

<listitem>
Поле <link id="respawned"/> в
<link id="processes"/>
было добавлено в <link id="version">версии</link> 5.
</listitem>

<listitem>
Поля <link id="header_time"/> и <link id="response_time"/> в
<link id="upstreams"/>
были добавлены в <link id="version">версии</link> 5.
</listitem>

<listitem>
Поле <link id="selected"/> в
<link id="upstreams"/>
было добавлено в <link id="version">версии</link> 4.
</listitem>

<listitem>
Состояние <link id="state">draining</link> в
<link id="upstreams"/>
было добавлено в <link id="version">версии</link> 4.
</listitem>

<listitem>
Поля <link id="id"/> и <link id="max_conns"/> в
<link id="upstreams"/>
были добавлены в <link id="version">версии</link> 3.
</listitem>

<listitem>
Поле <literal>revalidated</literal> в <link id="caches"/>
было добавлено в <link id="version">версии</link> 3.
</listitem>

<listitem>
<link id="server_zones"/>, <link id="caches"/>
и <link id="load_timestamp"/>
были добавлены в <link id="version">версии</link> 2.
</listitem>

</list>
</para>

</section>

</module>