<!-- review: finished -->

<a id="http-upstream-probe"></a>

# Upstream Probe

Реализует активные проверки работоспособности (health probes)
для [Upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).

<a id="configuration-example-46"></a>

## Пример конфигурации

```nginx
server {
    listen ...;

    location /backend {
        ...
        proxy_pass http://backend;

        upstream_probe backend_probe
            uri=/probe
            port=10004
            interval=5s
            test=$good
            essential
            fails=3
            passes=3
            max_body=10m
            mode=idle;
    }
}
```

<a id="directives-49"></a>

## Директивы

<a id="index-0"></a>

<a id="u-upstream-probe"></a>

### upstream_probe (PRO)

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream_probe` имя [`uri=`адрес] [`port=`число] [`interval=`время] [`method=`метод] [`test=`условие] [`essential` [`persistent`]] [`fails=`число] [`passes=`число] [`max_body=`размер] [`mode=``always` | `idle` | `onfail`] [`ping`] [`ping_timeout=`время];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию                                                                             | —                                                                                                                                                                                                                                                                 |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | location                                                                                                                                                                                                                                                          |

Задает активную проверку работоспособности серверов тех [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream),
которые указаны в директивах [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [uwsgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass) и т. д.
в том же контексте `location`, где находится директива `upstream_probe`.
При этом Angie регулярно выполняет запросы согласно указанным параметрам
к каждому серверу в составе апстрима.

Сервер проходит проверку, если запрос к нему успешно выполняется с учетом всех
параметров самой директивы `upstream_probe` и всех параметров, влияющих на
использование апстримов тем контекстом `location`, где она задана. Это
касается в том числе директив [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream),
[uwsgi_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream) и пр., а также [proxy_set_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header) и т. д.

Чтобы использовать проверки,
в апстриме необходима зона разделяемой памяти ([zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)).
Для одного апстрима можно определить несколько проверок.

Могут быть заданы следующие параметры:

| `имя`                | Обязательное имя проверки.                                                                                                                                                                                                                                                                                                                                                   |
|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `uri`                | URI запроса, который добавляется к аргументу [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass),<br/>[uwsgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass) и т. д. По умолчанию — `/`.                                                                                      |
| `port`               | Альтернативный порт для запроса.                                                                                                                                                                                                                                                                                                                                             |
| `interval`           | Интервал между проверками. По умолчанию — `5s`.                                                                                                                                                                                                                                                                                                                              |
| `method`             | HTTP-метод запроса проверки. По умолчанию — `GET`.                                                                                                                                                                                                                                                                                                                           |
| `test`               | Проверяемое при запросе условие; задается строкой с переменными.<br/>Если результат подстановки переменных — `""` или `"0"`,<br/>проверка не пройдена.                                                                                                                                                                                                                       |
| `essential`          | Если параметр задан, то изначально состояние сервера подлежит уточнению<br/>и клиентские запросы не передаются ему, пока проверка не будет пройдена.                                                                                                                                                                                                                         |
| `persistent`         | Установка этого параметра требует сначала включить `essential`;<br/>серверы с `persistent`, работавшие до<br/>[перезагрузки конфигурации](https://angie.software//angie/docs/configuration/configfile.md#configfile-reloading),<br/>начинают получать запросы без необходимости сначала пройти эту проверку.                                                                 |
| `fails`              | Число последовательных неуспешных запросов,<br/>при котором проверка считает сервер неработающим.<br/>По умолчанию — 1.                                                                                                                                                                                                                                                      |
| `passes`             | Число последовательных успешных запросов,<br/>при котором проверка считает сервер работающим.<br/>По умолчанию — 1.                                                                                                                                                                                                                                                          |
| `max_body`           | Максимальный объем памяти для тела ответа.<br/>По умолчанию — `256k`.                                                                                                                                                                                                                                                                                                        |
| `mode`               | Режим проверки в зависимости от работоспособности серверов:<br/><br/>- `always` — серверы проверяются независимо от состояния;<br/>- `idle` — проверяются неработающие серверы, а также серверы,<br/>  где с последнего клиентского запроса прошло время `interval`.<br/>- `onfail` — проверяются серверы только в неработающем состоянии.<br/><br/>По умолчанию — `always`. |
| `ping` (PRO)         | Использует ICMP echo запросы вместо HTTP-проверок.<br/>Требует сборки Angie с `--with-http_upstream_probe_icmp`.<br/>Несовместим с `test`, `port`,<br/>`method` и `uri`.                                                                                                                                                                                                     |
| `ping_timeout` (PRO) | Таймаут ожидания ICMP echo ответа.<br/>По умолчанию — `1s`.                                                                                                                                                                                                                                                                                                                  |

Пример:

```nginx
upstream backend {
    zone backend 1m;

    server backend1.example.com;
    server backend2.example.com;
}

map $upstream_status $good {
    200     "1";
}

server {
    listen ...;

    location /backend {
        ...
        proxy_pass http://backend;

        upstream_probe backend_probe
            uri=/probe
            port=10004
            interval=5s
            test=$good
            essential
            persistent
            fails=3
            passes=3
            max_body=10m
            mode=idle;
    }
}
```

Детали работы:

- Изначально сервер не получает клиентские запросы,
  пока не пройдет  *все* заданные для него проверки с параметром `essential`
  (пропуская помеченные как `persistent`, если конфигурация перезагружена
  и до этого сервер считался работающим).
  Если таких проверок нет, сервер считается работающим.
- Сервер считается неработающим и не получает клиентские запросы,
  если  *какая-либо* заданная для него проверка достигает своего порога `fails`
  или сам сервер достигает порога [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails).
- Чтобы неработающий сервер снова мог считаться работающим,
   *все* заданные для него проверки должны достичь своего порога `passes`;
  после этого учитывается порог [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails).

<a id="built-in-variables-15"></a>

## Встроенные переменные

Модуль `http_upstream_probe` поддерживает следующие встроенные переменные:

<a id="v-upstream-probe"></a>

### `$upstream_probe` (PRO)

Имя активной сейчас проверки [upstream_probe](#u-upstream-probe).

<a id="v-upstream-probe-body"></a>

### `$upstream_probe_body` (PRO)

Тело ответа от сервера,
полученного при проверке [upstream_probe](#u-upstream-probe).
Его размер ограничен параметром `max_body`.