upstream-log: Записывает логи запросов к upstream в указанном формате
Установка на Debian/Ubuntu
Эти документы относятся к APT пакету nginx-module-upstream-log, предоставленному репозиторием GetPageSpeed Extras.
- Настройте репозиторий APT, как описано в настройке APT репозитория.
- Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-upstream-log
Показать дистрибутивы и архитектуры
| Дистрибутив | Версия | Компонент | Архитектуры |
|-------------|-------------------|------------|----------------|
| debian | bookworm | main | amd64, arm64 |
| debian | bookworm-mainline | main | amd64, arm64 |
| debian | trixie | main | amd64, arm64 |
| debian | trixie-mainline | main | amd64, arm64 |
| ubuntu | focal | main | amd64, arm64 |
| ubuntu | focal-mainline | main | amd64, arm64 |
| ubuntu | jammy | main | amd64, arm64 |
| ubuntu | jammy-mainline | main | amd64, arm64 |
| ubuntu | noble | main | amd64, arm64 |
| ubuntu | noble-mainline | main | amd64, arm64 |
ngx_http_upstream_log_module
Модуль ngx_http_upstream_log_module записывает логи запросов к upstream в указанном формате, как и модуль ngx_http_log_module. Большая часть работы этого модуля происходит от ngx_http_log_module.
Описание
В отличие от модуля журналов доступа, логи будут записываться в конце каждого запроса к upstream. Если во время обработки запроса были задействованы несколько серверов, лог upstream записывается в конце каждого контакта. Если происходит внутренний редирект из одной группы серверов в другую, инициированный “X-Accel-Redirect” или error_page, лог upstream также будет записан в конце каждого контакта.
~~Этот модуль также предоставляет ряд переменных для логирования upstream. Многие из этих переменных начинаются с $upstream_last_, что используется для их отличия от переменных в ngx_http_upstream. Эти переменные возвращают только информацию, связанную с текущим контактом с upstream, или информацию, связанную с последним контактом с upstream. Запятые и двоеточия не используются для записи информации о нескольких контактах с upstream.~~
Примечание: Этот модуль больше не экспортирует никаких дополнительных переменных. Дополнительные переменные upstream были перенесены в ngx_http_extra_variables_module.
Использование этого модуля очень похоже на модуль ngx_http_log_module. Просто используйте директиву upstream_log для настройки пути, формата и конфигурации для записи буферизованного лога.
Статус
Этот модуль Nginx в настоящее время считается экспериментальным. Проблемы и PR приветствуются, если вы столкнетесь с какими-либо проблемами.
Пример
http {
log_format access '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
log_format upstream '$remote_addr $upstream_last_addr [$time_local] "$upstream_method $upstream_uri" '
'$upstream_last_status $upstream_last_response_length $upstream_last_bytes_sent $upstream_last_bytes_received '
'$upstream_last_connect_time $upstream_last_header_time $upstream_last_response_time';
upstream cluster {
server 192.168.0.1:80;
server 192.168.0.2:80;
}
server {
listen 80;
access_log logs/access.log access;
upstream_log logs/upstream.log upstream;
location / {
proxy_pass http://cluster;
}
}
}
Директива
upstream_log
- Синтаксис: upstream_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]; upstream_log off;
- Значение по умолчанию: -;
- Контекст: http, server, location, if в location, limit_except
Устанавливает путь, формат и конфигурацию для записи буферизованного лога. Несколько логов могут быть указаны на одном уровне конфигурации. Логгирование в syslog может быть настроено путем указания префикса “syslog:” в первом параметре. Специальное значение off отменяет все директивы upstream_log на текущем уровне. В отличие от директивы access_log, эта директива не принимает предопределенный формат "combined". Сначала необходимо определить формат лога с помощью директивы log_format, а затем ссылаться на него с помощью этой директивы.
Если используется либо параметр buffer, либо gzip, записи в лог будут буферизоваться.
Размер буфера не должен превышать размер атомарной записи в файл на диск. Для FreeBSD этот размер неограничен.
Когда буферизация включена, данные будут записываться в файл:
- если следующая строка лога не помещается в буфер;
- если буферизованные данные старше, чем указано параметром flush;
- когда рабочий процесс повторно открывает файлы лога или завершает работу. Если используется параметр gzip, то буферизованные данные будут сжиматься перед записью в файл. Уровень сжатия можно установить от 1 (самый быстрый, меньшее сжатие) до 9 (самый медленный, лучшее сжатие). По умолчанию размер буфера равен 64K байт, а уровень сжатия установлен на 1. Поскольку данные сжимаются атомарными блоками, файл лога можно разжимать или читать с помощью “zcat” в любое время.
Пример:
upstream_log /path/to/log.gz upstream gzip flush=5m;
Для успешной работы сжатия gzip, nginx должен быть собран с библиотекой zlib. Путь к файлу может содержать переменные, но такие логи имеют некоторые ограничения:
- пользователь, учетные данные которого используются рабочими процессами, должен иметь разрешения на создание файлов в директории с такими логами;
- буферизованные записи не работают;
- файл открывается и закрывается для каждой записи в лог. Однако поскольку дескрипторы часто используемых файлов могут храниться в кэше, запись в старый файл может продолжаться в течение времени, заданного параметром valid директивы open_log_file_cache;
- при каждой записи в лог проверяется наличие корня директории запроса, и если его не существует, лог не создается. Поэтому разумно указать как root, так и upstream_log на одном уровне конфигурации:
Параметр if позволяет включать условное логгирование. Запрос не будет записываться в лог, если условие оценивается как “0” или пустая строка. В следующем примере последние запросы с кодами ответа 2xx и 3xx не будут записываться в лог:
server { root /spool/vhost/data/$host; upstream_log /spool/vhost/logs/$host; ...map $upstream_status $upstream_loggable { ~(?:^|:\s|,\s)[23][0-9]{2} 0; default 1; } upstream_log /path/to/upstream.log upstream if=$upstream_loggable;