Финляндии от 390р
Обычный error_log в Nginx хорошо показывает явные ошибки: файл не найден, upstream не отвечает, не хватает прав, истёк таймаут. Но иногда этого мало: запрос «зависает» только у одного пользователя, редирект срабатывает не так, как ожидалось, location выбирается странно, а в обычных логах почти тишина.
В таких случаях помогает nginx debug log — подробный отладочный журнал, где Nginx пишет внутренние этапы обработки соединения и запроса. На рабочем VDS включать его для всего трафика опасно: за несколько минут можно получить гигабайты логов и лишнюю нагрузку на диск.
Правильный практический подход — включать debug-лог только для нужного IP через директиву debug_connection, быстро воспроизводить проблему, забирать фрагмент журнала и сразу возвращать обычный режим логирования.
Debug-лог — инструмент точечной диагностики, а не постоянного мониторинга. Держите его включённым ровно столько, сколько нужно для воспроизведения проблемы.
Когда nginx debug log действительно нужен
У Nginx есть уровни журналирования: error, warn, notice, info, debug и другие. На production-серверах обычно используют warn или error, чтобы лог не разрастался и содержал только важные события. Уровень debug принципиально другой: он пишет много внутренних деталей обработки соединения.
Debug-лог полезен, когда нужно понять:
- какой
serverилиlocationвыбрал Nginx для конкретного запроса; - как сработали
rewrite,try_files,mapили внутренний редирект; - на каком этапе появляется редкая ошибка 400, 403, 404, 499, 502 или 504;
- как Nginx подключается к upstream, отправляет заголовки и читает ответ;
- не мешают ли keepalive, HTTP/2, буферы или чтение тела запроса;
- почему проблема проявляется только у одного клиента или тестовой машины.
Важно понимать границу применимости. Debug-лог не заменяет access-лог, трассировку приложения, профилировщик PHP/Node.js/Python или анализ SQL-запросов. Он отвечает на вопрос «что делал Nginx внутри своей обработки запроса». Если ошибка живёт в бизнес-логике приложения, Nginx покажет только внешние признаки: передал запрос upstream, дождался ответа, получил таймаут или разрыв соединения.
Главное условие: Nginx должен быть собран с --with-debug
Директива error_log debug сама по себе ещё не гарантирует подробный вывод. Nginx должен быть собран с опцией --with-debug. Если этой опции нет, конфигурация может пройти проверку, но настоящих debug-сообщений вы не увидите.
Проверьте текущую сборку:
nginx -V 2>&1 | grep -- '--with-debug'Если команда вывела строку с --with-debug, можно переходить к настройке. Если вывода нет, посмотрите полный набор параметров:
nginx -V 2>&1На разных дистрибутивах ситуация отличается. Где-то поддержка debug уже включена в обычный пакет, где-то есть отдельный бинарник nginx-debug, а иногда потребуется пакет из другого репозитория или отдельная сборка.
command -v nginx-debugЕсли nginx-debug найден, не запускайте его вручную поверх работающего сервиса без проверки путей. На production-сервере важно сохранить те же конфиги, модули, PID-файл и systemd-юнит, иначе можно диагностировать не тот экземпляр Nginx.
Debian и Ubuntu
Сначала проверьте уже установленный Nginx. Часто этого достаточно:
nginx -V 2>&1 | grep -- '--with-debug'Если поддержки нет, обновите индекс пакетов и посмотрите доступные варианты:
sudo apt update
apt-cache search nginx | grep -Ei 'debug|nginx'После установки или замены пакета обязательно снова проверьте nginx -V. Не ориентируйтесь только на название пакета: состав сборки может отличаться между версиями дистрибутива и репозиториями.
AlmaLinux, Rocky Linux, CentOS Stream, Oracle Linux и Fedora
В RHEL-based дистрибутивах и Fedora логика та же: сначала смотрим параметры текущей сборки, затем ищем доступный debug-вариант в подключённых репозиториях.
nginx -V 2>&1 | grep -- '--with-debug'
dnf search nginx | grep -Ei 'debug|nginx'Если Nginx установлен из стороннего репозитория, не смешивайте пакеты из разных источников без необходимости. Разные сборки могут отличаться набором динамических модулей, путями к ним и настройками systemd. Для рабочего VDS безопаснее сначала проверить пакет на staging-сервере или хотя бы сохранить текущую конфигурацию и список установленных пакетов.
Минимальная безопасная схема: error_log debug плюс debug_connection
Для точечной отладки нужны две части. Первая — включить уровень debug в error_log. Вторая — ограничить отладку директивой debug_connection. Она указывается в контексте events и принимает IP-адрес или подсеть.
Пример для одного IPv4-адреса администратора:
error_log /var/log/nginx/debug.log debug;
events {
worker_connections 1024;
debug_connection 203.0.113.10;
}Если у вас уже есть блок events, не создавайте второй. Добавьте debug_connection в существующий блок. В итоговой конфигурации Nginx должен быть один основной блок events.
Можно указать несколько адресов, например IPv4 и IPv6:
error_log /var/log/nginx/debug.log debug;
events {
worker_connections 1024;
debug_connection 203.0.113.10;
debug_connection 2001:db8:1234::10;
}Можно указать подсеть, если тестовые клиенты выходят через небольшой офисный диапазон:
error_log /var/log/nginx/debug.log debug;
events {
worker_connections 1024;
debug_connection 203.0.113.0/24;
}С подсетями будьте осторожны. Чем шире диапазон, тем больше соединений попадёт в отладку. На публичном VDS не стоит включать debug для больших сетей «на всякий случай», особенно если сайт посещаемый или получает много фоновых запросов от ботов.
Россия
Нидерланды
Финляндия
Где размещать debug-лог
Технически error_log можно задавать в разных контекстах: глобально, внутри http, server, location. Для диагностики через debug_connection часто удобнее задать отдельный файл на верхнем уровне конфигурации, чтобы не смешивать отладку с обычным журналом ошибок.
error_log /var/log/nginx/debug.log debug;Так проще запустить tail, передать файл коллеге, вырезать нужный временной диапазон и потом удалить лог. Если писать debug в основной /var/log/nginx/error.log, он быстро станет шумным, а ротация может сработать в неудобный момент.
Перед включением проверьте каталог и права. В Debian/Ubuntu пользователь Nginx часто называется www-data:
sudo install -d -o root -g adm -m 0750 /var/log/nginx
sudo touch /var/log/nginx/debug.log
sudo chown www-data:adm /var/log/nginx/debug.logВ RHEL-based системах чаще используется пользователь nginx:
sudo install -d -o root -g nginx -m 0750 /var/log/nginx
sudo touch /var/log/nginx/debug.log
sudo chown nginx:nginx /var/log/nginx/debug.logЕсли включён SELinux и файл создавался нестандартным способом, проверьте контекст:
sudo restorecon -Rv /var/log/nginxЕсли не уверены, от какого пользователя работают процессы, посмотрите их напрямую:
ps -o user,group,comm -C nginxПошаговая инструкция: включаем debug только для своего IP
Шаг 1. Узнайте внешний IP тестового клиента
Нужен именно тот IP, с которого TCP-соединение приходит на Nginx. Если вы подключены через корпоративный NAT, VPN или мобильного оператора, адрес может меняться. Надёжный способ — выполнить тестовый запрос к сайту и посмотреть последние строки access-лога.
sudo tail -n 50 /var/log/nginx/access.logЕсли у виртуального хоста отдельный access-лог, смотрите его. Сверяйте не только IP, но и время, host, URL и user agent, чтобы не перепутать себя с другим клиентом.
Если сайт стоит за reverse proxy, балансировщиком или CDN, в соединении к вашему Nginx клиентом будет IP прокси, а не реальный пользовательский адрес. Директивы real IP меняют переменные вроде $remote_addr для логов и приложения, но debug_connection фильтрует адрес сокета. В таком случае отладку придётся включать по адресу прокси, использовать отдельный тестовый backend или временный обходной домен.
Шаг 2. Сохраните текущую конфигурацию
Перед изменениями полезно сделать быстрый снимок основного файла и итоговой конфигурации со всеми include-файлами:
sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.before-debug
sudo nginx -T > /tmp/nginx-full-config-before-debug.txtКоманда nginx -T помогает увидеть, где уже задан error_log, какие виртуальные хосты подключены и нет ли неожиданного переопределения в других файлах.
Шаг 3. Добавьте error_log debug и debug_connection
Откройте основной конфиг:
sudo editor /etc/nginx/nginx.confДобавьте или измените error_log на верхнем уровне:
error_log /var/log/nginx/debug.log debug;В существующий блок events добавьте ваш IP:
events {
worker_connections 1024;
debug_connection 203.0.113.10;
}Если в блоке уже есть другие настройки, оставьте их и добавьте только строку debug_connection. Не удаляйте worker_connections, use и другие параметры, если они были настроены ранее.
Шаг 4. Проверьте конфигурацию и выполните graceful reload
Сначала проверьте синтаксис:
sudo nginx -tЕсли всё хорошо, примените конфигурацию без остановки сервиса:
sudo systemctl reload nginxПроверьте статус:
systemctl status nginx --no-pagerЕсли reload не удался, не продолжайте диагностику. Сначала исправьте ошибку, которую показал nginx -t или systemd. Частые причины — опечатка в контексте директивы, неверный путь к файлу лога или второй блок events.
Шаг 5. Воспроизведите проблему и смотрите лог
Откройте отдельную SSH-сессию и следите за debug-файлом:
sudo tail -f /var/log/nginx/debug.logЗатем с тестового IP выполните запрос, который воспроизводит проблему. Удобно добавить уникальный маркер, чтобы быстро найти нужный фрагмент:
curl -I 'https://example.test/problem-url?debug_marker=fastfox_test_001'В реальной команде используйте свой домен. Если диагностируете POST-запрос, загрузку файла или API-метод, воспроизводите минимальный безопасный сценарий без персональных данных.
Как понять, что debug_connection работает
После reload файл debug.log не обязан сразу заполниться. Debug-сообщения пишутся только для соединений, которые соответствуют debug_connection. Если файл пустой, проверьте базовые условия.
- текущий внешний IP совпадает с указанным в
debug_connection; - вы подключаетесь именно к этому Nginx, а не к другому frontend-серверу;
- Nginx собран с
--with-debug; - после изменения был выполнен
systemctl reload nginx; - директива добавлена в блок
events; - файл
/var/log/nginx/debug.logдоступен для записи; - тестовый запрос попадает на тот же узел, где включена отладка.
Типичные строки debug-лога выглядят примерно так:
2026/01/15 12:10:11 [debug] 12345#12345: *701 accept: 203.0.113.10:53422 fd:15
2026/01/15 12:10:11 [debug] 12345#12345: *701 http process request line
2026/01/15 12:10:11 [debug] 12345#12345: *701 http request line: "GET /problem-url?debug_marker=fastfox_test_001 HTTP/2.0"
2026/01/15 12:10:11 [debug] 12345#12345: *701 test location: "/"
2026/01/15 12:10:11 [debug] 12345#12345: *701 using configuration "/"Число после звёздочки, например *701, — идентификатор соединения. По нему удобно фильтровать один поток событий:
sudo grep ' \*701 ' /var/log/nginx/debug.logЕсли запросов много, сначала найдите строку с уникальным маркером, затем возьмите connection id и отфильтруйте связанный фрагмент.
Что искать в debug-логе
Debug-лог подробный, поэтому двигайтесь от симптома. Если проблема с выбором location, ищите строки test location, using configuration, internal redirect. Если проблема с upstream, ищите connect to upstream, http upstream, upstream timed out, recv, send.
Для диагностики try_files полезны строки, где Nginx проверяет файлы на диске. Для FastCGI и PHP-FPM смотрите, какой socket или TCP-адрес используется, какие параметры передаются и на каком этапе появляется таймаут. Для proxy_pass обращайте внимание на итоговый URI, особенно если в конфигурации есть нюансы со слешем в конце proxy_pass и location.
Хороший практический приём — параллельно держать обычный access-лог с расширенным форматом, где есть request time, upstream time и request id. Debug-лог объясняет внутренние шаги, а access-лог даёт компактную сводку по статусу и времени.
Как не дать debug.log занять весь диск
Даже при debug_connection лог может расти быстро, если тестовый клиент открывает много соединений, браузер загружает десятки ресурсов, а сайт использует HTTP/2. На небольшом VDS это особенно чувствительно: переполненный диск может ударить по Nginx, базе данных и systemd-журналу.
Перед включением проверьте свободное место:
df -h /var/log
sudo du -sh /var/log/nginxВо время диагностики можно наблюдать размер файла:
watch -n 2 'ls -lh /var/log/nginx/debug.log'На production-сервере обычно достаточно 1–5 минут debug-лога. Если за это время проблема не воспроизвелась, лучше отключить отладку, уточнить сценарий и включить снова.
Можно заранее добавить отдельное правило logrotate для debug-файла. Но ротация не означает, что debug можно держать постоянно: она защищает диск, но не убирает лишнюю нагрузку на запись и не решает вопрос приватности данных.
/var/log/nginx/debug.log {
size 100M
rotate 3
missingok
notifempty
compress
create 0640 nginx nginx
sharedscripts
postrotate
systemctl reload nginx >/dev/null 2>&1 || true
endscript
}В Debian/Ubuntu для строки create часто нужно заменить пользователя и группу на www-data adm или на значения, принятые в вашей системе. После изменения logrotate-конфига проверьте его в debug-режиме:
sudo logrotate -d /etc/logrotate.d/nginx-debugКак отключить debug-лог и вернуть обычный режим
После воспроизведения проблемы не оставляйте error_log debug в конфигурации. Верните прежний уровень, например warn или error, и удалите или закомментируйте debug_connection.
error_log /var/log/nginx/error.log warn;
events {
worker_connections 1024;
}Затем проверьте конфигурацию и перезагрузите Nginx:
sudo nginx -t
sudo systemctl reload nginxПосле отключения можно сжать или очистить временный debug-файл:
sudo gzip -9 /var/log/nginx/debug.log
sudo install -o root -g root -m 0600 /dev/null /var/log/nginx/debug.logЕсли лог нужен для дальнейшего анализа, лучше вырезать только релевантный фрагмент по времени или connection id, а не хранить весь файл. Так меньше риск случайно передать лишние cookie, токены, приватные URL, внутренние IP и домены.
Частые ошибки при настройке debug_connection
Директива стоит не в том контексте
debug_connection работает в контексте events. Если поставить её внутрь http, server или location, Nginx выдаст ошибку конфигурации.
Перед Nginx стоит прокси
В access-логе вы можете видеть реальный IP благодаря realip-модулю, но debug_connection фильтрует адрес соединения на уровне сокета. Если соединение пришло от прокси, фильтр должен соответствовать адресу прокси.
Включили debug для всех
Если прописать только error_log debug и не использовать debug_connection, отладочные сообщения могут пойти для всего трафика. На тестовом стенде это допустимо, на боевом VDS — почти всегда плохая идея.
Забыли про IPv6
Если у домена есть AAAA-запись, браузер администратора может подключаться по IPv6, а вы указали только IPv4. Проверьте access-лог и добавьте IPv6-адрес отдельной строкой debug_connection.
Смотрите не тот файл
В конфигурации может быть несколько error_log: глобальный, внутри http, в конкретном server. Команда nginx -T помогает увидеть итоговую картину.
Безопасность и приватность debug-логов
Debug-лог может содержать больше информации, чем обычный error-лог: URI, заголовки, сведения о внутренней маршрутизации, upstream-адреса, иногда чувствительные параметры. Не публикуйте полный debug-файл в открытых местах и не прикладывайте его целиком к задачам без предварительной очистки.
- включайте debug только на короткое время;
- ограничивайте отладку конкретным IP через
debug_connection; - не воспроизводите проблему на реальных пользовательских данных, если можно сделать тестовый запрос;
- перед передачей лога удаляйте cookie, токены, приватные URL и внутренние адреса, если они не нужны для анализа;
- после диагностики удаляйте или архивируйте файл с ограниченными правами;
- учитывайте внутренние политики хранения логов и требования к персональным данным.
Особенно внимательно относитесь к URL с query string. Многие приложения по ошибке передают в параметрах одноразовые токены, email или идентификаторы восстановления доступа. Debug-лог сохранит то, что увидел Nginx.
Короткий runbook для боевого VDS
Если нужно действовать быстро, используйте компактный порядок. Сначала проверяем поддержку debug:
nginx -V 2>&1 | grep -- '--with-debug'Сохраняем текущую конфигурацию:
sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.before-debug
sudo nginx -T > /tmp/nginx-full-config-before-debug.txtДобавляем в /etc/nginx/nginx.conf отдельный debug-лог и IP администратора:
error_log /var/log/nginx/debug.log debug;
events {
worker_connections 1024;
debug_connection 203.0.113.10;
}Применяем:
sudo nginx -t
sudo systemctl reload nginxВоспроизводим проблему и смотрим лог:
sudo tail -f /var/log/nginx/debug.logПосле диагностики возвращаем обычный уровень логирования, убираем debug_connection, снова проверяем конфигурацию и делаем reload:
sudo nginx -t
sudo systemctl reload nginxЕсли у вас несколько серверов за балансировщиком, сначала убедитесь, на какой именно узел попадает тестовый запрос. Иначе можно включить debug на одном сервере, а воспроизводить проблему на другом.
Итоги
nginx debug log — мощный инструмент, но пользоваться им нужно точечно. Рабочая схема для VDS выглядит так: проверить --with-debug, задать отдельный error_log debug, ограничить отладку через debug_connection на конкретный IP, быстро воспроизвести проблему, забрать нужный фрагмент и отключить debug.
Такой подход даёт максимум диагностической информации без лишнего риска для диска, производительности и приватности. Если держать под рукой короткий runbook и заранее помнить про прокси, IPv6 и права на лог-файл, отладка Nginx становится обычной управляемой процедурой администратора.
