<!-- review: finished -->

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

# Log

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

Os logs são escritos no contexto de um `location` onde o processamento termina. Este pode ser um `location` diferente do original se um [redirecionamento interno](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#internal) ocorrer durante o processamento da requisição.

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

## Exemplo de Configuração

```nginx
log_format compression '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $bytes_sent '
                       '"$http_referer" "$http_user_agent" "$gzip_ratio"';

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

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

## Diretivas

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

<a id="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 logs/access.log combined;`<br/>(o caminho depende do [parâmetro de compilação](https://pt.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-log-path`) |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location, limit_except                                                                                                                                   |

Define o path, format e configurações de escrita em buffer para o log. Múltiplos logs podem ser usados no mesmo nível de configuração. O log para [syslog](https://pt.angie.software//angie/docs/configuration/processing.md#syslog-logging) é configurado especificando o prefixo "syslog:" no primeiro parâmetro. O valor especial off cancela todas as diretivas access_log para o nível atual. Se nenhum formato for especificado, o formato predefinido "combined" é usado.

Se o tamanho do buffer for especificado usando o parâmetro `buffer` ou o parâmetro `gzip` for especificado, a escrita será feita 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 são escritos no arquivo:

* se a próxima linha de log não couber no buffer;
* se os dados no buffer estiveram lá por mais tempo que o intervalo de tempo especificado pelo parâmetro flush;
* ao [reabrir o arquivo de log](https://pt.angie.software//angie/docs/configuration/runtime.md#log-rotation) ou terminar o processo worker.

Se o parâmetro `gzip` for especificado, o buffer será comprimido antes de escrever no arquivo. O nível de compressão pode ser definido no intervalo de 1 (mais rápido, mas pior compressão) a 9 (mais lento, mas 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 usando o utilitário **zcat**.

Exemplo:

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

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

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

* o [usuário](https://pt.angie.software//angie/docs/configuration/modules/core.md#user) sob cujas credenciais os processos worker executam deve ter permissões para criar arquivos no 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 frequentemente usados podem ser armazenados em cache, durante a rotação de logs dentro do tempo especificado pelo parâmetro valid da diretiva [open_log_file_cache](#open-log-file-cache), a escrita pode continuar no arquivo antigo.
* para cada escrita de log, a existência do diretório raiz para a requisição é verificada — se este diretório não existir, o log não é criado. Portanto [root](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#root) e [access_log](#access-log) devem ser descritos no mesmo nível de configuração:

```nginx
server {
    root       /spool/vhost/data/$host;
    access_log /spool/vhost/logs/$host;
    ...
```

O parâmetro `if` habilita o log condicional. Uma requisição não será registrada se o resultado da avaliação da condição for `"0"` ou uma string vazia. No exemplo a seguir, requisições com códigos de resposta 2xx e 3xx não serão registradas:

```nginx
map $status $loggable {
    ~^[23]  0;
    default 1;
}

access_log /path/to/access.log combined if=$loggable;
```

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

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

### log_format

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

Especifica o formato do log.

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

Ao usar `default`, 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á escrito no log como o valor.

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".

Linhas de cabeçalho enviadas ao cliente começam com o prefixo `sent_http_`,
por exemplo, `$sent_http_content_range`.

O formato predefinido `combined` sempre existe na configuração:

```nginx
log_format combined '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';
```

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

<a id="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)  | http, server, location                                                                                                 |

Define um cache que armazena descritores de arquivo de logs frequentemente usados cujos nomes são especificados usando variáveis. 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 foi acessado durante este tempo.<br/>O padrão é 10 segundos.                                                      |
| `min_uses` | Define o número mínimo de usos do arquivo durante o tempo especificado pelo parâmetro `inactive`, após o qual o descritor de arquivo permanecerá aberto no cache.<br/>O padrão é 1. |
| `valid`    | Especifica após que tempo verificar se o arquivo ainda existe sob o mesmo nome.<br/>O 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;
```