<!-- review: finished -->

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

# Log

Модуль записывает логи запросов в указанном формате.

Логи записываются в контексте `location`, где заканчивается обработка. Это может быть `location`, отличный от первоначального, если в процессе обработки запроса происходит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal).

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

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

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

## Директивы

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

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

### access_log

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `access_log` путь [формат [`buffer=`размер] [`gzip=`степень]] [`flush=`время] [`if=`условие]];<br/><br/>`access_log` `off`;                                             |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию                                                                             | `access_log logs/access.log combined;`<br/>(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-log-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server, location, if в location, limit_except                                                                                                                     |

Задает путь, формат и настройки буферизованной записи в лог. На одном уровне конфигурации может использоваться несколько логов. Запись в [syslog](https://angie.software//angie/docs/configuration/processing.md#syslog-logging) настраивается указанием префикса "syslog:" в первом параметре. Специальное значение off отменяет все директивы access_log для текущего уровня. Если формат не указан, то используется предопределенный формат "combined".

Если задан размер буфера с помощью параметра `buffer` или указан параметр `gzip`, то запись будет буферизованной.

#### WARNING
Размер буфера должен быть не больше размера атомарной записи в дисковый файл. Для FreeBSD этот размер неограничен.

При включенной буферизации данные записываются в файл:

* если очередная строка лога не помещается в буфер;
* если данные в буфере находятся дольше интервала времени, заданного параметром flush;
* при [переоткрытии лог-файла](https://angie.software//angie/docs/configuration/runtime.md#log-rotation) или завершении рабочего процесса.

Если задан параметр `gzip`, то буфер будет сжиматься перед записью в файл. Степень сжатия может быть задана в диапазоне от 1 (быстрее, но хуже сжатие) до 9 (медленнее, но лучше сжатие). По умолчанию используются буфер размером 64К байт и степень сжатия 1. Данные сжимаются атомарными блоками, и в любой момент времени лог-файл может быть распакован или прочитан с помощью утилиты **zcat**.

Пример:

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

#### NOTE
Для поддержки gzip-сжатия логов Angie должен быть собран с библиотекой zlib.

В пути файла можно использовать переменные, но такие логи имеют некоторые ограничения:

* [пользователь](https://angie.software//angie/docs/configuration/modules/core.md#user), с правами которого работают рабочие процессы, должен иметь права на создание файлов в каталоге с такими логами;
* не работает буферизация;
* файл открывается для каждой записи в лог и сразу же после записи закрывается. Следует однако иметь в виду, что поскольку дескрипторы часто используемых файлов могут храниться в кэше, то при ротации логов в течение времени, заданного параметром valid директивы [open_log_file_cache](#open-log-file-cache), запись может продолжаться в старый файл.
* при каждой записи в лог проверяется существование корневого каталога для запроса — если этот каталог не существует, то лог не создается. Поэтому [root](https://angie.software//angie/docs/configuration/modules/http/index.md#root) и [access_log](#access-log) нужно описывать на одном уровне конфигурации:

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

Параметр `if` включает условную запись в лог. Запрос не будет записываться в лог, если результатом вычисления условия является `"0"` или пустая строка. В следующем примере запросы с кодами ответа 2xx и 3xx не будут записываться в лог:

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

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `log_format` имя [`escape`= `default` | `json` | `none` ] строка ...;   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| По умолчанию                                                                             | `log_format combined "...";`                                            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http                                                                    |

Задает формат лога.

Параметр `escape` позволяет задать экранирование символов `json` или
`default` в переменных, по умолчанию используется `default`.
Значение `none` отключает экранирование символов.

При использовании `default` символы """, "\\", а также символы со
значениями меньше 32 или больше 126 экранируются как "\\xXX". Если значение
переменной не найдено, то в качестве значения в лог будет записываться дефис
"-".

При использовании `json` экранируются все символы, недопустимые в JSON
строках: символы """ и "\\" экранируются как "\\"" и "\\\\", символы со
значениями меньше 32 экранируются как "\\n", "\\r", "\\t", "\\b", "\\f" или
"\\u00XX".

Строки заголовка, переданные клиенту, начинаются с префикса `sent_http_`,
например, `$sent_http_content_range`.

В конфигурации всегда существует предопределенный формат `combined`:

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

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `open_log_file_cache` `max=`N [`inactive=`время] [`min_uses=`N] [`valid=`время];<br/><br/>`open_log_file_cache` `off`;   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| По умолчанию                                                                             | `open_log_file_cache off;`                                                                                               |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server, location                                                                                                   |

Задает кэш, в котором хранятся дескрипторы файлов часто используемых логов, имена которых заданы с использованием переменных. Параметры:

| `max`      | Задает максимальное число дескрипторов в кэше; при переполнении кэша наименее востребованные (LRU) дескрипторы закрываются.                                                              |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inactive` | Задает время, после которого кэшированный дескриптор закрывается, если к нему не было обращений в течение этого времени.<br/>По умолчанию — 10 секунд.                                   |
| `min_uses` | Задает минимальное число использований файла в течение времени, заданного параметром `inactive`, после которого дескриптор файла будет оставаться открытым в кэше.<br/>По умолчанию — 1. |
| `valid`    | Указыает, через какое время нужно проверять, что файл еще существует под тем же именем.<br/>По умолчанию  — 60 секунд.                                                                   |
| `off`      | Запрещает кэширование.                                                                                                                                                                   |

Пример использования:

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