upstream-log: Записывает журналы запросов к upstream в заданном формате
Установка
Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:
- RedHat Enterprise Linux 7, 8, 9 и 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 и Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-upstream-log
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-upstream-log
Включите модуль, добавив следующее в начале файла /etc/nginx/nginx.conf:
load_module modules/ngx_http_upstream_log_module.so;
Этот документ описывает nginx-module-upstream-log v0.1.1, выпущенный 6 января 2026 года.
В отличие от модуля журнала доступа, записи будут производиться в конце каждого запроса к 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, чтобы задать путь, формат и конфигурацию для буферизированной записи в журнал.
Синопсис
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;
GitHub
Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-upstream-log.