Отладка

Если у вас возникла техническая проблема, но нужное решение не удалось найти в других разделах, задайте нам вопрос на форуме сообщества или в 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:

error_log /path/to/log debug;

И перезагрузите конфигурацию:

$ sudo angie -t && sudo service angie reload

В шаблонных Docker-образах c включенным отладочным логом также можно использовать переменную окружения ANGIE_ERROR_LOG_SEVERITY:

$ docker run -it --rm -e ANGIE_BINARY="angie-debug" \
-e ANGIE_ERROR_LOG_SEVERITY="debug" \
docker.angie.software/angie:templated

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

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

error_log /path/to/log debug;

http {
   server {
     error_log /path/to/log;
    # ...

Во избежание этого уберите строку, переопределяющую error_log, либо задайте в ней уровень debug:

error_log /path/to/log debug;

http {
   server {
     error_log /path/to/log debug;
   #  ...

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

Расположение директивы 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 отключен, в файле - уровень info

        # ...
    }

    server {

        listen 80;
        server_name another.com;

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

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

Чтобы сохранить сбор отладочной информации для конкретного сервера, но направить ее в другой файл, необходимо также указать уровень 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 включен, но пишется в отдельный файл

        # ...
    }
}

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

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

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

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
   --- 2025-07-03 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: ручная настройка

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

root soft core 0          # по умолчанию отключает аварийные дампы
root hard core unlimited  # позволяет увеличить лимит размера

Затем увеличьте лимит размера аварийного дампа с помощью ulimit, после чего перезапустите Angie, чтобы воспроизвести условия сбоя:

$ sudo ulimit -c unlimited
$ sudo cd <путь к установочному каталогу Angie>
$ sudo sbin/angie  # или sbin/angie-debug

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

$ sudo ls -al <путь к рабочему каталогу Angie>  # по умолчанию, см. /proc/sys/kernel/core_pattern
  ...
  -rw-r----- 1 root root 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

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

$ sudo service angie restart

Если Angie установлен вручную:

$ sudo cd <путь к установочному каталогу Angie>
$ sudo sbin/angie

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

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

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