<!-- review: finished -->

<a id="stream-upstream"></a>

# Upstream

Fornece contexto para descrever grupos de servidores que podem ser usados na diretiva [proxy_pass](https://pt.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass).

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

## Exemplo de Configuração

```nginx
upstream backend {
    hash $remote_addr consistent;
    zone backend 1m;

    server backend1.example.com:1935  weight=5;
    server unix:/tmp/backend3;
    server backend3.example.com       service=_example._tcp resolve;

    server backup1.example.com:1935   backup;
    server backup2.example.com:1935   backup;
}

resolver 127.0.0.53 status_zone=resolver;

server {
    listen 1936;
    proxy_pass backend;
}
```

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

## Diretivas

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

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

### upstream

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream` name { ... }   |
|-------------------------------------------------------------------------------------------|---------------------------|
| Padrão                                                                                    | —                         |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                    |

Descreve um grupo de servidores. Os servidores podem escutar em portas diferentes. Além disso, servidores escutando em TCP e sockets de domínio UNIX podem ser misturados.

Exemplo:

```nginx
upstream backend {
    server backend1.example.com:1935 weight=5;
    server 127.0.0.1:1935            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:1935 resolve;

    server backup1.example.com:1935  backup;
}
```

<a id="s-round-robin"></a>

Por padrão, as conexões são distribuídas entre os servidores usando um método de balanceamento round-robin ponderado. No exemplo acima, cada 7 conexões serão distribuídas da seguinte forma: 5 conexões vão para backend1.example.com:1935 e uma conexão para cada um dos segundo e terceiro servidores.

Se ocorrer um erro durante a comunicação com um servidor, a conexão será passada para o próximo servidor, e assim por diante até que todos os servidores funcionais sejam tentados. Se a comunicação com todos os servidores falhar, a conexão será fechada.

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

<a id="s-u-server"></a>

### server

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server` address [parameters];   |
|-------------------------------------------------------------------------------------------|----------------------------------|
| Padrão                                                                                    | —                                |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                         |

Define o endereço e outros parâmetros de um servidor. O endereço pode ser especificado como um nome de domínio ou endereço IP com uma porta obrigatória, ou como um caminho de socket de domínio UNIX especificado após o prefixo `unix:`. Um nome de domínio que resolve para vários endereços IP define múltiplos servidores de uma vez.

Os seguintes parâmetros podem ser definidos:

| `weight=`number    | Define o peso do servidor; por padrão, 1.                                                                                                                                                                                                                         |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_conns=`number | Limita o número máximo de conexões ativas simultâneas para o servidor com proxy. O valor padrão é `0`, significando que não há limite. Se o grupo de servidores não residir na [memória compartilhada](#s-u-zone), a limitação funciona por cada processo worker. |

<a id="s-max-fails"></a>

`max_fails=`number — define o número de tentativas malsucedidas
de comunicação com o servidor
que devem acontecer na duração definida por [fail_timeout](#s-fail-timeout)
para considerar o servidor indisponível;
ele é então tentado novamente após a mesma duração.

Aqui, uma tentativa malsucedida é um erro ou timeout ao estabelecer uma
conexão com o servidor.

#### NOTE
Se uma diretiva `server` em um grupo resolve para múltiplos servidores,
sua configuração `max_fails` se aplica a cada servidor individualmente.

Se um upstream contém apenas um servidor
após todas as suas diretivas `server` serem resolvidas,
a configuração `max_fails` não tem efeito e será ignorada.

| `max_fails=1`   | O número padrão de tentativas.             |
|-----------------|--------------------------------------------|
| `max_fails=0`   | Desabilita a contabilização de tentativas. |

<a id="s-fail-timeout"></a>

`fail_timeout=`time — define o período de tempo durante o qual um número especificado de
tentativas malsucedidas de comunicação com o servidor ([max_fails](#s-max-fails)) deve acontecer para considerar o servidor indisponível.
O servidor então permanece indisponível pela mesma quantidade de tempo
antes de ser tentado novamente.

Por padrão, isso é definido como 10 segundos.

#### NOTE
Se uma diretiva `server` em um grupo resolve para múltiplos servidores,
sua configuração `fail_timeout` se aplica a cada servidor individualmente.

Se um upstream contém apenas um servidor
após todas as suas diretivas `server` serem resolvidas,
a configuração `fail_timeout` não tem efeito e será ignorada.

| `backup`      | Marca o servidor como um servidor de backup. Ele receberá requisições quando os servidores primários estiverem indisponíveis.                                                                                                     |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `down`        | Marca o servidor como permanentemente indisponível.                                                                                                                                                                               |
| `drain` (PRO) | Marca o servidor como drenando; isso significa<br/>que ele recebe apenas requisições das sessões<br/>que foram vinculadas anteriormente com [sticky](#s-u-sticky).<br/>Caso contrário, ele se comporta de forma similar a `down`. |

#### WARNING
O parâmetro `backup` não pode ser usado junto com os métodos de balanceamento de carga [hash](#s-u-hash) e [random](#s-u-random).

Os parâmetros `down` e `drain` são mutuamente exclusivos.

<a id="s-reresolve"></a>

| `resolve`      | Habilita o monitoramento de mudanças na lista de endereços IP que<br/>corresponde a um nome de domínio, atualizando-a sem recarregar a configuração.<br/>O grupo deve residir em uma<br/>[zona de memória compartilhada](#s-u-zone);<br/>além disso, um [resolver](https://pt.angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver) deve ser definido.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `service=`name | Habilita a resolução de registros DNS SRV e define o nome do serviço.<br/>Para que este parâmetro funcione, o parâmetro resolve também deve ser especificado,<br/>sem especificar a porta do servidor no nome do host.<br/><br/>Se não houver pontos no nome do serviço,<br/>o nome é formado de acordo com o padrão RFC:<br/>o nome do serviço é prefixado com `_`,<br/>então `_tcp` é adicionado após um ponto.<br/>Assim, o nome do serviço `http` resultará em `_http._tcp`.<br/><br/>O Angie resolve os registros SRV<br/>combinando o nome do serviço normalizado e o nome do host<br/>e obtendo a lista de servidores para a combinação via DNS,<br/>junto com suas prioridades e pesos.<br/><br/>- Registros SRV de prioridade máxima<br/>  (aqueles que compartilham o valor mínimo de prioridade)<br/>  resolvem para servidores primários,<br/>  e outros registros tornam-se servidores de backup.<br/>  Se `backup` for definido com `server`,<br/>  registros SRV de prioridade máxima resolvem para servidores de backup,<br/>  e outros registros são ignorados.<br/>- O peso é similar ao parâmetro `weight` da diretiva `server`.<br/>  Se o peso for definido tanto pela diretiva quanto pelo registro SRV,<br/>  o peso definido pela diretiva é usado. |

Este exemplo irá procurar o registro `_http._tcp.backend.example.com`:

```nginx
server backend.example.com service=http resolve;
```

| `sid=`id   | Define o ID do servidor no grupo. Se o parâmetro não for especificado,<br/>o ID é definido como um hash MD5 hexadecimal<br/>do endereço IP e porta ou caminho do socket de domínio UNIX.   |
|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

<a id="s-slow-start"></a>

| `slow_start=`time   | Define o [tempo](https://pt.angie.software//angie/docs/configuration/configfile.md#syntax) para um servidor recuperar seu peso<br/>ao retornar ao serviço<br/>com os métodos de balanceamento de carga [round-robin](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream.md#round-robin) ou [least_conn](#s-u-least-conn).<br/><br/>Se o parâmetro estiver definido<br/>e um servidor for novamente considerado saudável<br/>após uma falha de acordo com [max_fails](#s-max-fails) e [upstream_probe (PRO)](https://pt.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe),<br/>o servidor gradualmente recupera seu peso designado<br/>durante o período de tempo especificado.<br/><br/>Se o parâmetro não estiver definido,<br/>em uma situação similar<br/>o servidor imediatamente começa a trabalhar com seu peso designado.   |
|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

#### NOTE
Se apenas um `server` for especificado no upstream,
`slow_start` não tem efeito e será ignorado.

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

<a id="s-u-state"></a>

### state (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `state` file;   |
|-------------------------------------------------------------------------------------------|-----------------|
| Padrão                                                                                    | —               |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream        |

Especifica o file onde a lista de servidores upstream é armazenada persistentemente.
Ao instalar a partir dos
[nossos pacotes](https://pt.angie.software//angie/docs/installation/index.md#install-packages),
um diretório dedicado
`/var/lib/angie/state/` (`/var/db/angie/state/` no FreeBSD)
é criado com as permissões apropriadas para armazenar tais arquivos,
então você só precisa adicionar o nome do arquivo na configuração:

```nginx
upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/<NOME DO ARQUIVO>;
}
```

O formato da lista de servidores aqui é similar ao `s_server`.
O conteúdo do arquivo muda sempre que servidores são modificados na
seção [/config/stream/upstreams/](https://pt.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-stream-upstreams-servers)
via API de configuração.
O arquivo é lido na inicialização do Angie ou no recarregamento da configuração.

#### WARNING
Para usar a diretiva `state` em um bloco `upstream`,
não deve haver diretivas `server` nele,
mas uma zona de memória compartilhada ([zone](#s-u-zone)) é necessária.

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

<a id="s-u-zone"></a>

### zone

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `zone` name [size];   |
|-------------------------------------------------------------------------------------------|-----------------------|
| Padrão                                                                                    | —                     |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream              |

Define o nome e tamanho da zona de memória compartilhada que armazena a configuração e estado de execução do grupo, compartilhada entre processos worker. Múltiplos grupos podem usar a mesma zona. Neste caso, é suficiente especificar o tamanho apenas uma vez.

#### NOTE
O conteúdo da zona só é preservado na recarga quando o `size`
configurado não muda. Qualquer alteração de tamanho — aumento ou
redução — faz com que a zona seja recriada vazia.

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

<a id="s-u-backup-switch"></a>

### backup_switch (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `backup_switch` `permanent`[=time];   |
|-------------------------------------------------------------------------------------------|---------------------------------------|
| Padrão                                                                                    | —                                     |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                              |

A diretiva habilita a capacidade de iniciar a seleção de servidor não do grupo primário,
mas do grupo *ativo*, ou seja, aquele onde um servidor foi encontrado com sucesso anteriormente.
Se um servidor não puder ser encontrado no grupo ativo para a próxima requisição,
e a busca se mover para o grupo de backup,
este grupo de backup se torna ativo,
e requisições subsequentes são primeiro direcionadas para servidores neste grupo.

Se o parâmetro `permanent` for definido sem um valor de [tempo](https://pt.angie.software//angie/docs/configuration/configfile.md#syntax),
o grupo permanece ativo após a seleção,
e a re-verificação automática de grupos com níveis de prioridade mais baixos não ocorre.
Se time for especificado,
o status ativo do grupo expira após o intervalo especificado,
e o balanceador de carga novamente verifica grupos com níveis de prioridade mais baixos,
retornando a eles se os servidores estiverem funcionando normalmente.

Exemplo:

```nginx
upstream media_backend {
    server primary1.example.com:1935;
    server primary2.example.com:1935;

    server reserve1.example.com:1935 backup;
    server reserve2.example.com:1935 backup;

    backup_switch permanent=2m;
}
```

Se o balanceador de carga alternar dos servidores primários para o grupo de backup,
todas as requisições subsequentes são tratadas por este grupo de backup por 2 minutos.
Após 2 minutos expirarem, o balanceador de carga re-verifica os servidores primários
e os torna ativos novamente se estiverem funcionando normalmente.

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

<a id="s-u-feedback"></a>

### feedback (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `feedback` variable [`inverse`] [`factor=`number] [`account=`condition_variable];   |
|-------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| Padrão                                                                                    | —                                                                                   |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                            |

Habilita um mecanismo de balanceamento de carga baseado em feedback para o `upstream`.
Ele ajusta dinamicamente as decisões de balanceamento de carga
multiplicando o peso de cada servidor proxy pela média do valor de feedback,
que muda ao longo do tempo baseado no valor da variable
e está sujeito a uma condição opcional.

Os seguintes parâmetros podem ser especificados:

| `variable`   | A variável da qual o valor de feedback é obtido.<br/>Ela deve representar uma métrica de desempenho ou saúde;<br/>assume-se que seja fornecida pelo servidor.<br/><br/>O valor é avaliado com cada resposta do servidor<br/>e considerado na média móvel<br/>de acordo com as configurações `inverse` e `factor`.                                                                                                                                                                                                                                                                                                                                                           |
|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inverse`    | Se o parâmetro estiver definido, o valor de feedback é interpretado inversamente:<br/>valores menores indicam melhor desempenho.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `factor`     | O fator pelo qual o valor de feedback é ponderado<br/>ao calcular a média.<br/>Valores válidos são inteiros de 0 a 99.<br/>O padrão é `90`.<br/><br/>A média é calculada usando a fórmula de [suavização exponencial](https://en.wikipedia.org/wiki/Exponential_smoothing).<br/><br/>Quanto maior o fator, menos os novos valores afetam a média;<br/>se `90` for especificado, 90% do valor anterior será considerado<br/>e apenas 10% do novo valor.                                                                                                                                                                                                                      |
| `account`    | Especifica uma variável de condição<br/>que controla como as conexões são contabilizadas no cálculo.<br/>O valor médio é atualizado com o valor de feedback<br/>apenas se a variável de condição<br/>não for igual a `""` ou `"0"`.<br/><br/>#### NOTE<br/>Por padrão, o tráfego de [sondas](https://pt.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)<br/>não é incluído no cálculo;<br/>combinar a variável [$upstream_probe](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)<br/>com `account` permite incluí-las<br/>ou até mesmo excluir todo o resto. |

Exemplo:

```nginx
upstream backend {

    zone backend 1m;

    feedback $feedback_value factor=80 account=$condition_value;

    server backend1.example.com:1935  weight=1;
    server backend2.example.com:1935  weight=2;
}

map $protocol $feedback_value {
    "TCP"                      100;
    "UDP"                      75;
    default                    10;
}

map $upstream_probe $condition_value {
    "high_priority" "1";
    "low_priority"  "0";
    default         "1";
}
```

Esta configuração categoriza servidores por níveis de feedback
baseados nos protocolos usados em sessões individuais,
e também adiciona uma condição em [$upstream_probe](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
para contabilizar apenas sondas `high_priority`
ou sessões regulares de cliente.

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

<a id="s-u-hash"></a>

### hash

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `hash` key [`consistent`];   |
|-------------------------------------------------------------------------------------------|------------------------------|
| Padrão                                                                                    | —                            |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                     |

Especifica um método de balanceamento de carga para o grupo onde o mapeamento cliente-servidor é determinado usando um valor de chave hash. A chave pode conter texto, variáveis e suas combinações. Note que qualquer adição ou remoção de servidores do grupo pode resultar no remapeamento da maioria das chaves para servidores diferentes. O método é compatível com a biblioteca Perl [Cache::Memcached](https://metacpan.org/pod/Cache::Memcached).

Exemplo de uso:

```nginx
hash $remote_addr;
```

Ao usar nomes de domínio que resolvem para múltiplos endereços IP
(por exemplo, com o parâmetro `resolve`),
o servidor não ordena os endereços recebidos, então sua ordem pode diferir
entre diferentes servidores, o que afeta a distribuição de clientes.
Para garantir distribuição consistente,
use o parâmetro `consistent`.

Se o parâmetro `consistent` for especificado, o método de hash consistente ketama será usado em vez do método acima. O método garante que quando um servidor é adicionado ou removido do grupo, apenas um número mínimo de chaves será remapeado para outros servidores. Usar o método para servidores de cache fornece uma taxa de acerto de cache mais alta. O método é compatível com a biblioteca Perl [Cache::Memcached::Fast](https://metacpan.org/pod/Cache::Memcached::Fast) com o parâmetro `ketama_points` definido como 160.

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

<a id="s-u-least-conn"></a>

### least_conn

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_conn`;   |
|-------------------------------------------------------------------------------------------|-----------------|
| Padrão                                                                                    | —               |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream        |

Especifica um método de balanceamento de carga para o grupo onde uma conexão é passada para o servidor com o menor número de conexões ativas, levando em conta os pesos dos servidores. Se vários servidores forem adequados, eles são selecionados ciclicamente (round-robin) com seus pesos levados em conta.

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

<a id="s-u-least-time"></a>

### least_time (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_time` `connect` | `first_byte` | `last_byte` [`factor=`number] [`account=`condition_variable];   |
|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| Padrão                                                                                    | —                                                                                                       |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                                |

Especifica um método de balanceamento de carga para o grupo onde a probabilidade de passar
uma conexão para um servidor ativo é inversamente proporcional ao seu tempo médio
de resposta; quanto menor ele for, mais conexões o servidor receberá.

| `connect`    | A diretiva leva em conta o tempo médio para estabelecer uma conexão.   |
|--------------|------------------------------------------------------------------------|
| `first_byte` | A diretiva usa o tempo médio para receber o primeiro byte da resposta. |
| `last_byte`  | A diretiva usa o tempo médio para receber a resposta completa.         |

| `factor`   | Executa a mesma função que [response_time_factor (PRO)](#s-u-response-time-factor),<br/>e o sobrescreve se o parâmetro for especificado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `account`  | Especifica uma variável de condição<br/>que controla quais conexões são contabilizadas no cálculo.<br/>O valor médio é atualizado<br/>apenas se a variável de condição da conexão<br/>não for igual a `""` ou `"0"`.<br/><br/>#### NOTE<br/>Por padrão, [sondas](https://pt.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)<br/>não são incluídas no cálculo;<br/>combinar a variável [$upstream_probe](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)<br/>com `account` permite incluí-las<br/>ou até mesmo excluir todo o resto. |

Os valores atuais são apresentados como `connect_time`, `first_byte_time`,
e `last_byte_time` no objeto `health` do servidor
entre as [métricas de upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) na API.

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

<a id="s-u-random"></a>

### random

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `random` [`two`];   |
|-------------------------------------------------------------------------------------------|---------------------|
| Padrão                                                                                    | —                   |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream            |

Especifica um método de balanceamento de carga para o grupo onde uma conexão é passada para um servidor selecionado aleatoriamente, levando em conta os pesos dos servidores.

Se o parâmetro opcional `two` for especificado, o Angie seleciona aleatoriamente dois servidores e então escolhe um servidor usando o método especificado. O método padrão é [least_conn](#s-u-least-conn), que passa a conexão para o servidor com o menor número de conexões ativas.

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

<a id="s-u-response-time-factor"></a>

### response_time_factor (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `response_time_factor` number;   |
|-------------------------------------------------------------------------------------------|----------------------------------|
| Padrão                                                                                    | `response_time_factor 90;`       |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                         |

Especifica para o método de balanceamento de carga [least_time (PRO)](#s-u-least-time) o fator
de suavização para o valor **anterior** ao calcular o tempo médio de resposta usando a
fórmula de [média móvel exponencialmente ponderada](https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average).

Quanto maior o number especificado, menos os novos valores afetam a média; se
`90` for especificado, 90% do valor anterior será considerado e apenas 10% do
novo valor. Valores válidos são de 0 a 99 inclusive.

Os resultados atuais do cálculo são apresentados como `connect_time` (tempo
para estabelecer uma conexão), `first_byte_time` (tempo para receber o primeiro
byte da resposta), e `last_byte_time` (tempo para receber a resposta completa) no
objeto `health` do servidor entre as [métricas de upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) na API.

#### NOTE
Apenas respostas bem-sucedidas são consideradas no cálculo;
o que constitui uma resposta mal-sucedida
é determinado pelas diretivas [proxy_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream).

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

<a id="s-u-sticky"></a>

### sticky

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky route` value...;<br/><br/>`sticky learn` `zone=`zone `create=`$create_var1... `lookup=`$lookup_var1... [`connect`] [`norefresh`] [`timeout=`time];<br/><br/>`sticky learn` `lookup=`$lookup_var1... `remote_action=`uri `remote_result=`$remote_var [`remote_uri=`uri];   |
|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Padrão                                                                                    | —                                                                                                                                                                                                                                                                                 |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                                                                                                                                                                                                          |

Configura sessões persistentes entre clientes e servidores upstream,
dependendo do modo especificado no primeiro parâmetro.
Para gradualmente tirar servidores com `sticky` de rotação,
você pode usar a opção `drain` (PRO) no bloco [server](#s-u-server).

#### WARNING
A diretiva `sticky` deve aparecer após todas as diretivas de método de balanceamento de carga,
caso contrário não funcionará.

modo `route`

Este modo usa identificadores de rota predefinidos
que podem ser incorporados em propriedades de conexão acessíveis ao Angie.
É menos flexível, pois depende de valores predefinidos,
mas é mais adequado se tais identificadores já estiverem em uso.

Aqui, ao estabelecer uma conexão, o servidor upstream
pode atribuir uma rota ao cliente e retornar seu identificador de uma forma
conhecida por ambas as partes.
O identificador de rota
deve usar o valor do parâmetro [sid](#s-reresolve)
da diretiva [server](#s-u-server).
Note que o parâmetro é adicionalmente hasheado
se a diretiva [sticky_secret](#s-u-sticky-secret) for especificada.

Conexões subsequentes de clientes que desejam usar esta rota
devem conter o identificador emitido pelo servidor, de tal forma
que ele termine em variáveis do Angie.

Os parâmetros da diretiva especificam strings que podem incluir variáveis
para roteamento. Para selecionar o servidor para onde a conexão de entrada é direcionada,
o primeiro valor não vazio é usado;
ele é então comparado com o parâmetro [sid](#s-reresolve)
da diretiva [server](#s-u-server).
Se a seleção do servidor falhar
ou o servidor selecionado não puder aceitar a conexão,
outro servidor será selecionado
de acordo com o método de balanceamento de carga configurado.

Aqui o Angie procura o identificador de rota na variável `$route`,
que recebe seu valor baseado em [$ssl_preread_server_name](https://pt.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-server-name)
(note que [ssl_preread](https://pt.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#s-ssl-preread) deve estar habilitado):

```nginx
stream {

    map $ssl_preread_server_name $route {

        a.example.com            a;
        b.example.com            b;
        default                  "";
    }

    upstream backend {

        server 127.0.0.1:8081 sid=a;
        server 127.0.0.1:8082 sid=b;

        sticky route $route;
    }

    server {

        listen 127.0.0.1:8080;

        ssl_preread on;

        proxy_pass backend;
    }
}
```

modo `learn` (PRO)

Neste modo, uma chave gerada dinamicamente é usada
para vincular um cliente a um servidor upstream específico;
este modo é mais flexível
pois atribui servidores dinamicamente,
armazena sessões em uma zona de memória compartilhada,
e suporta várias formas de passar identificadores de sessão.

Aqui, uma sessão é criada
com base em propriedades de conexão vindas do servidor upstream.
Os parâmetros `create` e `lookup` listam variáveis
que especificam como novas sessões são criadas e as existentes são encontradas.
Ambos os parâmetros podem ser usados múltiplas vezes.

O identificador de sessão é o valor da primeira variável não vazia
especificada com `create`;
por exemplo, isso poderia ser
o [nome do servidor upstream](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#v-server-name).

Sessões são armazenadas em uma zona de memória compartilhada;
seu nome e tamanho são especificados pelo parâmetro `zone`.
Se uma sessão não foi acessada dentro do [tempo](https://pt.angie.software//angie/docs/configuration/configfile.md#syntax)
especificado por `timeout`, ela é excluída.
O valor padrão é 1 hora.

Por padrão, o Angie estende o tempo de vida da sessão
atualizando o timestamp do último acesso cada vez que ela é usada.
O parâmetro `norefresh` altera este comportamento:
a sessão expira estritamente pelo timeout, mesmo se estiver sendo usada.

Conexões subsequentes de clientes que desejam usar uma sessão
devem conter seu identificador.
O parâmetro `lookup` procura o identificador de sessão na conexão
usando a lista especificada de variáveis,
parando na primeira não vazia.
Se nada for encontrado, a requisição é considerada nova.
O valor do identificador encontrado
é comparado com sessões na memória compartilhada.
Se a seleção do servidor falhar
ou o servidor selecionado não puder lidar com a conexão,
outro servidor será selecionado
de acordo com o método de balanceamento de carga configurado.

O parâmetro `connect` permite criar uma sessão
imediatamente após estabelecer uma conexão com o servidor upstream.
Sem ele, a sessão é criada apenas após o processamento da conexão estar completo.
(No caso de conexões UDP, sessões são criadas imediatamente após a seleção do servidor.)

No exemplo, o Angie cria e procura sessões
usando a variável [$rdp_cookie](https://pt.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#v-rdp-cookie):

```nginx
stream {

    upstream backend {

        server 127.0.0.1:3390;
        server 127.0.0.1:3391;

        sticky learn lookup=$rdp_cookie create=$rdp_cookie zone=sessions:1m;
    }

    server {

        listen 127.0.0.1:3389;

        rdp_preread on;

        proxy_pass backend;
    }
}
```

modo `learn` com `remote_action` (PRO 1.10.0+)

Os parâmetros `remote_action` e `remote_result`
permitem atribuir e gerenciar identificadores de sessão dinamicamente
usando um armazenamento de sessão remoto (PRO).

Diferentemente do modo `learn` com `zone`,
este modo não armazena sessões localmente em cache
e consulta o armazenamento remoto para cada conexão.

O parâmetro `remote_action` deve apontar para um `location`
no contexto [client](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#client).
O parâmetro `remote_uri` especifica o URI da requisição HTTP do cliente
para o `location` especificado.
Por padrão, é `/`.
O valor de `remote_uri` pode conter variáveis.

O princípio geral de operação deste modo é o seguinte:
se um identificador de sessão não for encontrado localmente,
o Angie envia uma subrequisição síncrona para um armazenamento remoto
especificado pelo parâmetro `remote_action`.

Quando uma nova conexão chega, o Angie executa as seguintes ações:

- Primeiro, o identificador de sessão é extraído da primeira variável não vazia
  na lista `lookup`.
  Se todas as variáveis estiverem vazias,
  o algoritmo normal de balanceamento de carga é usado sem sessões persistentes.
- Então o Angie envia uma subrequisição HTTP síncrona para o armazenamento remoto
  especificado pelo parâmetro `remote_action`, que deve conter
  em um formato compreendido pelo armazenamento:
  - o identificador de *sessão* do parâmetro `lookup`
    (na configuração, esta é a
    variável [$sticky_sessid](#v-s-sticky-sessid));
  - o identificador do *servidor* pré-selecionado:
    o valor do parâmetro `sid=` da diretiva `server`,
    se especificado,
    ou o hash MD5 do nome do servidor
    (na configuração, esta é a
    variável [$sticky_sid](#v-s-sticky-sid)).

  As variáveis `$sticky_sessid` e `$sticky_sid` são automaticamente
  exportadas para o contexto HTTP com o prefixo `stream_`:
  `$stream_sticky_sessid`, `$stream_sticky_sid`.
  Isso permite usá-las diretamente em diretivas HTTP,
  por exemplo via cabeçalhos HTTP usando [proxy_set_header](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header).
- O armazenamento remoto processa a requisição e retorna uma resposta HTTP:

  Uma resposta com código 200, 201 ou 204 confirma o servidor selecionado.
  O armazenamento remoto pode simultaneamente
  retornar um identificador de servidor alternativo em um cabeçalho HTTP ou no
  corpo da resposta (PRO); ele pode ser extraído via `remote_result`.

  Ao receber qualquer outro código HTTP do armazenamento
  (incluindo erros de rede e timeouts)
  ou um identificador de servidor inexistente,
  o Angie usa o servidor originalmente selecionado.

O identificador do servidor é extraído da resposta do armazenamento remoto
via o parâmetro `remote_result`:
ele pode especificar variáveis
com o prefixo `upstream_http_`,
que são criadas automaticamente pelo Angie para acessar
cabeçalhos de resposta HTTP do armazenamento remoto,
ou [$sent_body](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#v-sent-body) para usar o corpo da resposta.
Por exemplo, o cabeçalho `X-Sid: server1` em tal resposta
torna-se acessível na variável `$upstream_http_x_sid`
com o valor `server1`.

Abaixo está um exemplo de configuração simplificado.
O armazenamento remoto retorna o identificador do servidor no cabeçalho `X-Sticky-Sid`
e assim confirma ou substitui a seleção do Angie:

```nginx
http {

    client {

        location @sticky_client1 {

            # usa variáveis do stream upstream;
            # ele adiciona essas variáveis ao contexto HTTP com o prefixo stream_*
            proxy_set_header X-Sticky-Sessid $stream_sticky_sessid;
            proxy_set_header X-Sticky-Sid $stream_sticky_sid;
            proxy_set_header X-Sticky-Last $msec;
            proxy_pass http://127.0.0.1:8080;

            proxy_cache remote;
            proxy_cache_valid 200 1d;
            proxy_cache_key $scheme$proxy_host$request_uri$stream_sticky_sessid;
        }
    }
}

stream {

    upstream u {

        server 127.0.0.1:8081 sid=backend-01;
        server 127.0.0.1:8082 sid=backend-02;

        sticky learn lookup=$remote_addr            # stream variable
        remote_action=@sticky_client1               # location from client block
        remote_result=$upstream_http_x_sticky_sid   # HTTP variable
        remote_uri=/foo;                            # default is /
    }

    server {

        listen 127.0.0.1:8080;
        proxy_pass u;
    }
}
```

Aqui, com a seguinte resposta do armazenamento remoto:

```none
HTTP/1.1 200 OK
...
X-Sticky-Sid: backend-01
X-Session-Info: active
```

Duas variáveis ficam disponíveis:

- `$upstream_http_x_sticky_sid`,
  com o valor `backend-01`;
- `$upstream_http_x_session_info`,
  com o valor `active`.

Como a variável `$upstream_http_x_sticky_sid`
é especificada no parâmetro `remote_result`,
seu valor será usado
para selecionar o servidor com `sid=backend-01`.

A diretiva `sticky` leva em consideração o estado dos servidores em [upstream](#s-u-upstream):

- Servidores marcados como `down` ou temporariamente indisponíveis devido a falhas
  são excluídos da seleção.
- Servidores que atingiram o número máximo de conexões
  (ao usar `max_conns`) são temporariamente ignorados.
- Servidores com a opção `drain` (PRO)
  podem ser selecionados para criar novas sessões no modo `sticky`
  quando os identificadores correspondem.
- Se um servidor anteriormente indisponível se recuperar,
  `sticky` automaticamente retoma seu uso.

O comportamento de `sticky` pode ser configurado adicionalmente
com as diretivas [sticky_secret](#s-u-sticky-secret) e [sticky_strict](#s-u-sticky-strict).
Se `sticky` falhar ao selecionar um servidor ou ele estiver indisponível,
a requisição será tratada de acordo com o método de balanceamento de carga selecionado,
a menos que a diretiva `sticky_strict` esteja habilitada.
No modo `sticky_strict on;`, a requisição é rejeitada com um erro.

Zonas de memória compartilhada
especificadas no parâmetro `zone` da diretiva `sticky`
não podem ser compartilhadas entre diferentes grupos `upstream`;
cada grupo deve usar sua própria zona.

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

<a id="s-u-sticky-secret"></a>

### sticky_secret

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_secret` string;   |
|-------------------------------------------------------------------------------------------|---------------------------|
| Padrão                                                                                    | —                         |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                  |

Adiciona string como salt à função hash MD5
para a diretiva [sticky](#s-u-sticky) no modo `route`.
String pode conter variáveis, por exemplo `$remote_addr`:

```nginx
upstream backend {
    server 127.0.0.1:8081 sid=a;
    server 127.0.0.1:8082 sid=b;

    sticky route $route;
    sticky_secret my_secret.$remote_addr;
}
```

O salt é adicionado após o valor com hash;
para verificar independentemente o mecanismo de hashing:

```console
$ echo -n "<VALUE><SALT>" | md5sum
```

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

<a id="s-u-sticky-strict"></a>

### sticky_strict

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_strict` `on` | `off`;   |
|-------------------------------------------------------------------------------------------|---------------------------------|
| Padrão                                                                                    | `sticky_strict off;`            |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                        |

Quando habilitado, o Angie retornará um erro de conexão para o cliente
se o servidor desejado estiver indisponível,
em vez de fazer fallback para outro servidor disponível,
que é o comportamento padrão quando nenhum servidor correspondente é encontrado.

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

## Variáveis Integradas

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

<a id="v-s-sticky-sessid"></a>

### `$sticky_sessid`

Usado com `remote_action` em [sticky](#s-u-sticky);
armazena o identificador de sessão inicial obtido de `lookup`.

<a id="v-s-sticky-sid"></a>

### `$sticky_sid`

Usado com `remote_action` em [sticky](#s-u-sticky);
armazena o identificador do servidor previamente associado à sessão.

`sticky_sid` contém o valor do parâmetro `sid=`
da diretiva `server` no bloco [upstream](#s-u-upstream), se especificado,
ou o hash MD5 do nome do servidor.

<a id="v-s-upstream-addr"></a>

### `$upstream_addr`

armazena o endereço IP e porta, ou o caminho para o socket de domínio UNIX do servidor upstream. Se vários servidores foram contatados durante o proxy, seus endereços são separados por vírgulas, por exemplo:

> 192.168.1.1:1935, 192.168.1.2:1935, unix:/tmp/sock

Se um servidor não puder ser selecionado, a variável mantém o nome do [grupo de servidores](#s-u-upstream).

<a id="v-s-upstream-bytes-received"></a>

### `$upstream_bytes_received`

número de bytes recebidos de um servidor upstream. Valores de várias conexões são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-s-upstream-addr).

<a id="v-s-upstream-bytes-sent"></a>

### `$upstream_bytes_sent`

número de bytes enviados para um servidor upstream. Valores de várias conexões são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-s-upstream-addr).

<a id="v-s-upstream-connect-time"></a>

### `$upstream_connect_time`

tempo para conectar ao servidor upstream; o tempo é mantido em segundos com resolução de milissegundos. Tempos de várias conexões são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-s-upstream-addr).

<a id="v-s-upstream-first-byte-time"></a>

### `$upstream_first_byte_time`

tempo para receber o primeiro byte de dados; o tempo é mantido em segundos com resolução de milissegundos. Tempos de várias conexões são separados por vírgulas como endereços na variável [$upstream_addr](#v-s-upstream-addr).

<a id="v-s-upstream-session-time"></a>

### `$upstream_session_time`

duração da sessão em segundos com resolução de milissegundos. Tempos de várias conexões são separados por vírgulas como endereços na variável [$upstream_addr](#v-s-upstream-addr).

<a id="v-s-upstream-sticky-status"></a>

### `$upstream_sticky_status`

Status das conexões sticky.

| `""`   | Conexão roteada para um grupo de servidores onde sticky não está habilitado.                                      |
|--------|-------------------------------------------------------------------------------------------------------------------|
| `NEW`  | Conexão não contém informações sticky.                                                                            |
| `HIT`  | Conexão com informações sticky roteada para o servidor desejado.                                                  |
| `MISS` | Conexão com informações sticky roteada para um servidor<br/>selecionado pelo algoritmo de balanceamento de carga. |

Valores de múltiplas conexões são separados por vírgulas e dois pontos,
similar aos endereços na variável [$upstream_addr](#v-s-upstream-addr).