Nginx access_log: свой формат и запись в файл

Категория: Nginx · Обновлено:

access_log задаёт файл и формат журнала запросов. Свой log_format позволяет писать JSON для ELK/Loki или только нужные поля: статус, время, upstream, request ID. Буферизация уменьшает число системных вызовов, а access_log off отключает запись для healthcheck и шумных путей.

Настроить JSON-журнал

Текст
http {
    log_format json_combined escape=json
        '{"time":"$time_iso8601",'
        '"remote_addr":"$remote_addr",'
        '"method":"$request_method",'
        '"uri":"$request_uri",'
        '"status":$status,'
        '"request_time":$request_time,'
        '"upstream_time":"$upstream_response_time",'
        '"request_id":"$request_id"}';

    access_log /var/log/nginx/access.log json_combined buffer=32k flush=5s;

    server {
        listen 80;

        location /health {
            access_log off;
            return 200 "ok";
        }
    }
}

log_format объявляется в http; имя json_combined затем используется в access_log. escape=json экранирует кавычки и управляющие символы, иначе JSON можно сломать URL с ". buffer=32k flush=5s копит записи в памяти и сбрасывает их раз в пять секунд; при аварийной остановке часть строк может потеряться.

$request_time — время обработки в секундах, $upstream_response_time — время ответа бэкенда (может быть -). $request_id генерируется Nginx и полезен для трассировки, но не заменяет X-Request-ID приложения. Для чувствительных query-параметров логируйте $uri, а не $request_uri.

Не пишите журнал в web-root и следите за правами: в логах могут быть IP, URL и заголовки. Настройте logrotate с copytruncate или сигналом USR1, иначе файл вырастет. Для syslog используйте access_log syslog:server=..., для нескольких форматов — несколько директив.

Проверьте nginx -t, сделайте запрос и убедитесь, что JSON парсится (jq .). Healthcheck с access_log off не должен появляться в файле. Не логируйте токены и cookies: они могут попасть в URL или заголовки.

Документация: ngx_http_log_module, log_format.