<!-- review: finished -->

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

# Log

O módulo escreve logs de requisição no formato especificado.

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

## Exemplo de Configuração

```nginx
log_format basic '$remote_addr [$time_local] '
                 '$protocol $status $bytes_sent $bytes_received '
                 '$session_time';

access_log /spool/logs/angie-access.log basic buffer=32k;
```

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

## Diretivas

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

<a id="s-access-log"></a>

### access_log

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `access_log` path [format [`buffer=`size] [gzip[=level]] [`flush=`time] [`if=`condition]];<br/><br/>`access_log` `off`;   |
|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Padrão                                                                                    | `access_log off;`                                                                                                         |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                            |

Define o path, format e configuração para uma escrita de log com buffer. Vários logs podem ser especificados no mesmo nível de configuração. O log para [syslog](https://pt.angie.software//angie/docs/configuration/processing.md#syslog-logging) pode ser configurado especificando o prefixo "syslog:" no primeiro parâmetro. O valor especial off cancela todas as diretivas access_log no nível atual.

Se o parâmetro `buffer` ou `gzip` for usado, as escritas no log
serão armazenadas em buffer.

#### WARNING
O tamanho do buffer não deve exceder o tamanho de uma escrita atômica em um arquivo de disco. Para FreeBSD este tamanho é ilimitado.

Quando o buffer está habilitado, os dados serão escritos no arquivo:

* se a próxima linha de log não couber no buffer;
* se os dados em buffer forem mais antigos que o intervalo de tempo especificado pelo parâmetro `flush`;
* quando um processo worker estiver [reabrindo arquivos de log](https://pt.angie.software//angie/docs/configuration/runtime.md#log-rotation) ou sendo encerrado.

Se o parâmetro `gzip` for usado, então o buffer será comprimido antes
de escrever no arquivo. O nível de compressão pode ser definido entre `1`
(mais rápido, menos compressão) e `9` (mais lento, melhor compressão). Por
padrão, um tamanho de buffer de `64K` bytes e nível de compressão `1` são
usados. Os dados são comprimidos em blocos atômicos, e a qualquer momento o arquivo de log pode
ser descomprimido ou lido pelo utilitário `"zcat"`.

Exemplo:

```nginx
access_log /path/to/log.gz basic gzip flush=5m;
```

#### NOTE
Para suporte à compressão gzip, o Angie deve ser compilado com a biblioteca zlib.

Variáveis podem ser usadas no caminho do arquivo, mas tais logs têm algumas restrições:

* o [usuário](https://pt.angie.software//angie/docs/configuration/modules/core.md#user) cujas credenciais são usadas pelos processos worker deve ter permissões para criar arquivos em um diretório com tais logs;
* o buffer não funciona;
* o arquivo é aberto para cada escrita de log e fechado imediatamente após a escrita. No entanto, como descritores de arquivos usados frequentemente podem ser armazenados em cache, a escrita pode continuar no arquivo antigo durante a rotação de log pelo tempo especificado pelo parâmetro valid da diretiva [open_log_file_cache](https://pt.angie.software//angie/docs/configuration/modules/http/http_log.md#open-log-file-cache).

O parâmetro if habilita o log condicional. Uma sessão não será logada se a condição for avaliada como "0" ou uma string vazia.

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

<a id="s-log-format"></a>

### log_format

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `log_format` name [`escape=``default` | `json` | `none`] string ...;   |
|-------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| Padrão                                                                                    | —                                                                      |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                 |

Especifica o formato do log, por exemplo:

```nginx
log_format proxy '$remote_addr [$time_local] '
                 '$protocol $status $bytes_sent $bytes_received '
                 '$session_time "$upstream_addr" '
                 '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"';
```

O parâmetro `escape` permite definir escape de caracteres `json` ou `default` em variáveis; por padrão, `default` é usado. O valor `none` desabilita o escape de caracteres.

Ao usar `default`, os caracteres """, "\\", e caracteres com valores menores que 32 ou maiores que 126 são escapados como "\\xXX". Se o valor da variável não for encontrado, um hífen "-" será logado.

Ao usar `json`, todos os caracteres não permitidos em strings JSON são escapados: caracteres """ e "\\" são escapados como "\\"" e "\\\\", caracteres com valores menores que 32 são escapados como "\\n", "\\r", "\\t", "\\b", "\\f", ou "\\u00XX".

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

<a id="s-open-log-file-cache"></a>

### open_log_file_cache

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `open_log_file_cache` `max=`N [`inactive=`time] [`min_uses=`N] [`valid=`time];<br/><br/>`open_log_file_cache` `off`;   |
|-------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Padrão                                                                                    | `open_log_file_cache off;`                                                                                             |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                         |

Define um cache que armazena os descritores de arquivo de logs usados frequentemente cujos nomes contêm variáveis. A diretiva tem os seguintes parâmetros:

| `max`      | Define o número máximo de descritores no cache; quando o cache transborda, os descritores menos recentemente usados (LRU) são fechados.                     |
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inactive` | Define o tempo após o qual um descritor em cache é fechado se não houve acessos durante este tempo; por padrão, 10 segundos.                                |
| `min_uses` | Define o número mínimo de usos do arquivo durante o tempo definido pelo parâmetro `inactive` para que o descritor permaneça aberto no cache; por padrão, 1. |
| `valid`    | Define o tempo após o qual deve ser verificado se o arquivo ainda existe com o mesmo nome; por padrão, 60 segundos.                                         |
| `off`      | Desabilita o cache.                                                                                                                                         |

Exemplo de uso:

```nginx
open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
```