<!-- review: finished -->

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

# Upstream Probe

O módulo implementa sondas de saúde ativas
para [Upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).

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

## Exemplo de Configuração

```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>

## Diretivas

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

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

### upstream_probe (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream_probe` name [`uri=`address] [`port=`number] [`interval=`time] [`method=`method] [`test=`condition] [`essential` [`persistent`]] [`fails=`number] [`passes=`number] [`max_body=`size] [`mode=``always` | `idle` | `onfail`] [`ping`] [`ping_timeout=`time];   |
|-------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Padrão                                                                                    | —                                                                                                                                                                                                                                                                      |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                                                                                                                                                                                                                                                               |

Define uma sonda de saúde ativa para servidores dentro dos grupos [upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream)
que são especificados em [proxy_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [uwsgi_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass) e diretivas similares
no mesmo contexto `location` da diretiva `upstream_probe`.
O Angie executa regularmente requisições de acordo com os parâmetros especificados
para cada servidor no grupo upstream.

Um servidor passa na sonda se a requisição para ele for bem-sucedida, considerando todas
as configurações de parâmetros da diretiva `upstream_probe` e todos os parâmetros que
controlam como os upstreams são usados pelo contexto `location` onde é definido.
Isso inclui as diretivas [proxy_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) e [uwsgi_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream),
etc., bem como [proxy_set_header](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header) e assim por diante.

Para usar as sondas,
o upstream deve ter uma zona de memória compartilhada ([zone](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)).
Um upstream pode ser configurado com várias sondas.

Os seguintes parâmetros são aceitos:

| `name`               | Nome obrigatório da sonda.                                                                                                                                                                                                                                                                                                                                             |
|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `uri`                | URI da requisição a ser anexado ao argumento de [proxy_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass),<br/>[uwsgi_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), etc. Por padrão — `/`.                                                                           |
| `port`               | Número de porta alternativo para a requisição da sonda.                                                                                                                                                                                                                                                                                                                |
| `interval`           | Intervalo entre sondas. Por padrão — `5s`.                                                                                                                                                                                                                                                                                                                             |
| `method`             | Método HTTP da requisição da sonda. Por padrão — `GET`.                                                                                                                                                                                                                                                                                                                |
| `test`               | A condição a ser verificada durante a requisição; definida como uma string com variáveis.<br/>Se a substituição de variável resultar em `""` ou `"0"`,<br/>a sonda falha.                                                                                                                                                                                              |
| `essential`          | Se definido, o estado inicial do servidor está sujeito à verificação<br/>e requisições de cliente não são encaminhadas para ele até que a sonda seja aprovada.                                                                                                                                                                                                         |
| `persistent`         | Definir este parâmetro requer habilitar `essential` primeiro;<br/>servidores `persistent` que estavam funcionando antes de um<br/>[recarregamento de configuração](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile-reloading)<br/>começam a receber requisições sem serem obrigados a passar nesta sonda primeiro.                        |
| `fails`              | Número de requisições consecutivas falhadas que<br/>tornam o servidor não saudável. Por padrão — 1.                                                                                                                                                                                                                                                                    |
| `passes`             | Número de requisições consecutivas bem-sucedidas que<br/>tornam o servidor saudável. Por padrão — 1.                                                                                                                                                                                                                                                                   |
| `max_body`           | Quantidade máxima de memória para o corpo da resposta. Por padrão — `256k`.                                                                                                                                                                                                                                                                                            |
| `mode`               | Modo da sonda, dependendo da saúde dos servidores:<br/><br/>- `always` — servidores são sondados independentemente de seu estado;<br/>- `idle` — sondas afetam servidores não saudáveis e servidores onde<br/>  `interval` passou desde a última requisição do cliente.<br/>- `onfail` — apenas servidores não saudáveis são sondados.<br/><br/>Por padrão — `always`. |
| `ping` (PRO)         | Usa requisições de echo ICMP em vez de sondas HTTP.<br/>Requer que o Angie seja compilado com `--with-http_upstream_probe_icmp`.<br/>Não é compatível com `test`, `port`,<br/>`method` ou `uri`.                                                                                                                                                                       |
| `ping_timeout` (PRO) | Timeout para aguardar uma resposta de echo ICMP.<br/>Por padrão — `1s`.                                                                                                                                                                                                                                                                                                |

Exemplo:

```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;
    }
}
```

Detalhes da operação da sonda:

- Inicialmente, o servidor não receberá requisições de cliente
  até que passe em *todas* as sondas `essential` configuradas para ele
  (pulando as `persistent` se a configuração foi recarregada
  e o servidor foi considerado saudável antes disso).
  Se não há tais sondas, o servidor é considerado saudável.
- O servidor é considerado não saudável e não receberá requisições de cliente
  se *qualquer* das sondas configuradas para ele atingir seu limite `fails`
  ou o próprio servidor atingir o limite [max_fails](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails).
- Para um servidor não saudável ser considerado saudável novamente,
  *todas* as sondas configuradas para ele devem atingir seus respectivos limites `passes`;
  depois disso, o limite [max_fails](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) é considerado.

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

## Variáveis Integradas

O módulo `http_upstream_probe` suporta as seguintes variáveis integradas:

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

### `$upstream_probe` (PRO)

Nome da [upstream_probe](#u-upstream-probe) atualmente ativa.

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

### `$upstream_probe_body` (PRO)

Corpo da resposta do servidor
recebido durante uma [upstream_probe](#u-upstream-probe);
seu tamanho é limitado por `max_body`.