Отладка

Если у вас возникла техническая проблема, но нужное решение не удалось найти в других разделах, задайте нам вопрос на форуме сообщества или в Telegram-канале.

Техническая поддержка для клиентов:

• https://support.angie.software

Отладочный лог

Отладочный лог следует включать перед самостоятельной диагностикой или по рекомендации технической поддержки.

Для этого запустите Angie, используя исполняемый файл с поддержкой отладки:

LinuxFreeBSDDockerСборка из исходников

В готовых пакетах для Linux файл angie-debug собран с поддержкой отладки:

$ ls -l /usr/sbin/ | grep angie

   lrwxrwxrwx 1 root root      13 Sep 21 18:58 angie -> angie-nodebug
   -rwxr-xr-x 1 root root 1561224 Sep 21 18:58 angie-debug
   -rwxr-xr-x 1 root root 1426056 Sep 21 18:58 angie-nodebug

Настройте запуск angie-debug:

$ sudo ln -fs angie-debug /usr/sbin/angie
$ sudo angie -t && sudo service angie upgrade

Запустится обновление исполняемого файла на лету.

Чтобы вернуться к обычному исполняемому файлу после окончания отладки:

$ sudo ln -fs angie-nodebug /usr/sbin/angie
$ sudo angie -t && sudo service angie upgrade

Примечание

Использование исполняемого файла с поддержкой отладки может незначительно снизить производительность; включение же отладочного лога может заметно снизить ее, а также увеличить расход места на диске.

Чтобы включить отладочный лог, задайте в конфигурации уровень debug с помощью директивы error_log (в шаблонных Docker-образах вместо этого используется переменная окружения, см. вкладку Docker ниже):

error_log /path/to/log debug;

Затем примените изменения:

LinuxFreeBSDDockerСборка из исходников

$ sudo angie -t && sudo service angie reload

Если вернуться на исполняемый файл без поддержки отладки, но оставить уровень debug в директиве error_log, Angie будет добавлять записи в лог на уровне info.

Расположение директивы

Расположение директивы error_log влияет на полноту собираемой отладочной информации.

Директива, указанная на более низком уровне конфигурации (например, внутри блока server или location), заменяет настройки логирования, заданные на более высоком уровне (например, на основном уровне конфигурации или внутри блока http).

Отладочный лог отключен для конкретного сервера

Если глобально включен отладочный лог, но для отдельного сервера error_log указан без уровня debug, то для этого сервера отладочная информация собираться не будет.

error_log /var/log/angie/error.log debug; # Глобальный отладочный лог

http {

    server {

        listen 80;
        server_name example.com;

        error_log /var/log/angie/example.com.error.log;
        # Отладочный лог для example.com отключен, в файле - уровень error

        # ...
    }

    server {

        listen 80;
        server_name another.com;

        # Для этого сервера будет использоваться глобальный отладочный лог
        # ...
    }
}

Сохранение отладочного лога на уровне сервера

Чтобы для конкретного сервера по-прежнему собиралась отладочная информация, уберите в нем переопределение error_log; чтобы направить эту информацию в другой файл, укажите в переопределении также уровень debug:

error_log /var/log/angie/error.log debug; # Глобальный отладочный лог

http {

    server {

        listen 80;
        server_name example.com;

        error_log /var/log/angie/example.com.error.log debug;
        # Отладочный лог для example.com включен, но пишется в отдельный файл

        # ...
    }
}

Лог для отдельных адресов

Можно включить отладочный лог только для указанных клиентских адресов:

error_log /path/to/log;

events {
  debug_connection 192.168.1.1;
  debug_connection 192.168.10.0/24;
}

Кольцевой буфер в памяти

Отладочный лог можно записывать в кольцевой буфер в памяти:

error_log memory:32m debug;

Запись в буфер в памяти на уровне debug не будет существенно влиять на производительность даже при высоких нагрузках. В этом случае лог можно извлечь при помощи GDB-скрипта, например:

set $log = ngx_cycle->log

while $log->writer != ngx_log_memory_writer
  set $log = $log->next
end

set $buf = (ngx_log_memory_buf_t *) $log->wdata
dump binary memory debug_log.txt $buf->start $buf->end

Аварийные дампы памяти

Аварийные дампы памяти помогают в расследовании сбоев. Прикладывайте их при обращении в поддержку. Для сборок из наших репозиториев мы поддерживаем отладочные символы в специальных пакетах. Они имеют те же имена, что и оригинальные пакеты, с добавлением суффикса -dbg, например angie-dbg.

Примечание

В этом разделе предполагается, что вы запускаете Angie от имени пользователя root (рекомендуется).

Linux: systemd

Чтобы включить сохранение аварийных дампов при запуске Angie как службы systemd (например, при установке из пакетов), измените настройки службы в файле /lib/systemd/system/angie.service:

[Service]
...
LimitCORE=infinity
LimitNOFILE=65535

Либо обновите глобальные настройки в файле /etc/systemd/system.conf:

[Manager]
...
DefaultLimitCORE=infinity
DefaultLimitNOFILE=65535

Затем перезагрузите конфигурацию службы и перезапустите Angie, чтобы воспроизвести условия сбоя:

$ sudo systemctl daemon-reload
$ sudo systemctl restart angie.service

После сбоя найдите файл аварийного дампа:

$ sudo coredumpctl -1 # опционально

   TIME                           PID   UID   GID SIG COREFILE  EXE
   --- 2026-10-16 11:05:40 GMT   1157     0     0  11 present   /usr/sbin/angie

$ sudo ls -al /var/lib/systemd/coredump/  # по умолчанию, см. также /etc/systemd/coredump.conf и /etc/systemd/coredump.conf.d/*.conf

  ...
  -rw-r----- 1 root root 177662 Jul 27 11:05 core.angie.0.6135489c850b4fb4a74795ebbc1e382a.1157.1590577472000000.lz4

Linux: ручная настройка

Этот раздел описывает Angie, запущенный без systemd, например собранный из исходников, и предполагает, что Angie из этой установки уже работает; в командах используются пути такой сборки по умолчанию в /usr/local/angie.

Куда ядро записывает файл аварийного дампа, зависит от /proc/sys/kernel/core_pattern. Если шаблон начинается с |, ядро передает дамп программе, указанной после этого символа, например systemd-coredump, даже если Angie запущен без systemd; в этом случае найдите файл аварийного дампа, как описано в разделе Linux: systemd, и пропустите шаги ниже, связанные с рабочим каталогом. Если шаблон — простое имя, например core, ядро записывает файл аварийного дампа в рабочий каталог аварийно завершившегося процесса; для рабочих процессов это по умолчанию каталог, из которого запущен Angie.

Рабочие процессы выполняются от имени учетной записи, которую задает директива user (nobody в сборке из исходников по умолчанию); если эта учетная запись не может писать в рабочий каталог, аварийный дамп при сбое не сохранится, поэтому создайте каталог для аварийных дампов:

$ sudo mkdir -p /var/tmp/angie-cores
$ sudo chown nobody /var/tmp/angie-cores

Укажите его директивой working_directory в контексте main файла /usr/local/angie/conf/angie.conf:

working_directory /var/tmp/angie-cores;

Затем увеличьте лимит размера аварийного дампа. Чтобы увеличить его только для рабочих процессов и обойтись без перезапуска, добавьте также директиву worker_rlimit_core, которая принимает размер, а не unlimited, и перезагрузите конфигурацию:

worker_rlimit_core 1g;

$ sudo /usr/local/angie/sbin/angie -s reload

Чтобы увеличить лимит и для главного процесса, вместо этого перезапустите Angie. По умолчанию sudo запускает команды с нулевым лимитом размера аварийного дампа, а команда ulimit меняет лимит только для оболочки, в которой выполнена, и запущенных из нее команд. Остановите работающий Angie, дождитесь завершения его главного процесса, а затем увеличьте лимит и запустите Angie в одной оболочке с правами root:

$ sudo /usr/local/angie/sbin/angie -s quit
$ while [ -e /usr/local/angie/logs/angie.pid ]; do sleep 1; done
$ sudo sh -c 'ulimit -c unlimited && exec /usr/local/angie/sbin/angie'

В сборке из исходников, сконфигурированной с --with-debug, поддержка отладки есть в самом /usr/local/angie/sbin/angie; отдельного исполняемого файла angie-debug в ней нет.

Проверьте лимит рабочего процесса: после перезапуска оба значения равны unlimited, а с worker_rlimit_core они показывают заданный размер в байтах:

$ grep 'core file' /proc/$(pgrep -n -f 'angie: worker process')/limits
Max core file size        unlimited            unlimited            bytes

Затем воспроизведите сбой. Если аварийный дамп сохранился, в логе ошибок (по умолчанию /usr/local/angie/logs/error.log) появится сообщение worker process PID exited on signal номер (core dumped); то же сообщение без (core dumped) означает, что дамп не сохранился из-за лимита или рабочего каталога. Найдите файл аварийного дампа:

$ sudo ls -al /var/tmp/angie-cores
  ...
  -rw------- 1 nobody nogroup 177662 Jul 27 11:05 core.1157

FreeBSD

Проверьте настройки аварийных дампов в файле /etc/sysctl.conf, при необходимости измените их:

kern.coredump=1                             # должно быть равно 1
kern.corefile=/path/to/core/files/%N.core   # нужен корректный путь

Либо обновите настройки во время выполнения:

$ sudo sysctl kern.coredump=1
$ sudo sysctl kern.corefile=/path/to/core/files/%N.core

В любом случае учетная запись, которую задает директива user, должна иметь право записи в каталог из kern.corefile: от ее имени выполняются рабочие процессы, и туда они записывают аварийные дампы.

Затем перезапустите Angie, чтобы воспроизвести условия сбоя. Если Angie установлен как служба:

$ sudo service angie restart

Если Angie установлен вручную, остановите его, дождитесь завершения его главного процесса, а затем увеличьте лимит размера аварийного дампа и запустите Angie в одной оболочке с правами root, как в Linux:

$ sudo <путь к установочному каталогу Angie>/sbin/angie -s quit
$ while [ -e <путь к установочному каталогу Angie>/logs/angie.pid ]; do sleep 1; done
$ sudo sh -c 'ulimit -c unlimited && exec <путь к установочному каталогу Angie>/sbin/angie'

После сбоя найдите файл аварийного дампа:

$ sudo ls -al <путь к файлам аварийных дампов>

  ...
  -rw------- 1 nobody nobody 9912320 Jul 27 11:05 angie.core