<!-- review: finished -->

<a id="troubleshooting"></a>

# Отладка

Если у вас возникла техническая проблема,
но нужное решение не удалось найти в других разделах,
задайте нам вопрос на [форуме сообщества](https://forum.angie.support/)
или в [Telegram-канале](https://t.me/angie_support).

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

- [https://support.angie.software](https://support.angie.software)
- [support@angie.software](mailto:support@angie.software)

<a id="debug-logging"></a>

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

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

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

Linux

В [готовых пакетах](https://angie.software//angie/docs/installation/index.md#install-packages) для Linux
файл `angie-debug` собран с включенным отладочным логом:

```console
$ 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`:

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

Запустится [обновление исполняемого файла на лету](https://angie.software//angie/docs/configuration/runtime.md#service-upgrade).

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

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

FreeBSD

В [готовых пакетах](https://angie.software//angie/docs/installation/index.md#install-packages) для FreeBSD
файл `angie-debug` собран с включенным отладочным логом:

```console
$ ls -l /usr/local/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`:

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

Запустится [обновление исполняемого файла на лету](https://angie.software//angie/docs/configuration/runtime.md#service-upgrade).

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

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

Docker

В [шаблонных Docker-образах](https://angie.software//angie/docs/installation/docker.md#docker-images)
можно переключиться на отладочную версию,
переопределив переменную окружения `ANGIE_BINARY`:

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

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

При самостоятельной сборке Angie
нужно [включить отладку](https://angie.software//angie/docs/installation/sourcebuild.md#configure) перед сборкой:

```console
$ ./configure --with-debug ...
```

После установки команда **angie -V** позволяет убедиться,
что отладочный лог включен:

```console
$ angie -V

  ...
  configure arguments: --with-debug ...
```

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

Чтобы включить отладочный лог,
задайте в конфигурации уровень `debug`
с помощью директивы [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log):

```nginx
error_log /path/to/log debug;
```

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

```console
$ sudo angie -t && sudo service angie reload
```

В [шаблонных Docker-образах](https://angie.software//angie/docs/installation/docker.md#docker-images)
c включенным отладочным логом
также можно использовать переменную окружения
`ANGIE_ERROR_LOG_SEVERITY`:

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

Если вернуться на исполняемый файл без поддержки отладки,
но оставить уровень `debug` в директиве [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log),
Angie будет добавлять записи в лог на уровне `info`.

Если переопределить [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log) в конфигурации,
но не указать в ней уровень `debug`, отладочный лог будет отключен.
Здесь переопределение лога на уровне [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server)
отключает отладочный лог для отдельного сервера:

```nginx
error_log /path/to/log debug;

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

Во избежание этого уберите строку, переопределяющую [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log),
либо задайте в ней уровень `debug`:

```nginx
error_log /path/to/log debug;

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

<a id="directive-location"></a>

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

Расположение директивы [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log)
влияет на полноту собираемой отладочной информации.

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

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

Если глобально включен отладочный лог,
но для отдельного сервера [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log) указан без уровня `debug`,
то для этого сервера отладочная информация собираться не будет.

```nginx
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`:

```nginx
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](https://angie.software//angie/docs/configuration/modules/core.md#error-log) не указан уровень логирования,
по умолчанию будет использоваться уровень `error`
и отладочная информация для этих блоков будет потеряна.

<a id="logging-specific-addresses"></a>

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

Можно включить отладочный лог только для
[указанных клиентских адресов](https://angie.software//angie/docs/configuration/modules/core.md#debug-connection):

```nginx
error_log /path/to/log;

events {
  debug_connection 192.168.1.1;
  debug_connection 192.168.10.0/24;
}
```

<a id="cyclic-memory-buffer"></a>

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

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

```nginx
error_log memory:32m debug;
```

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

```console
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
```

<a id="core-dumps"></a>

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

Аварийные дампы памяти помогают в расследовании сбоев.
Прикладывайте их при [обращении в поддержку](#troubleshooting).
Для сборок из [наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
мы поддерживаем отладочные символы в специальных пакетах.
Они имеют те же имена, что и оригинальные пакеты,
с добавлением суффикса `-dbg`, например `angie-dbg`.

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

<a id="linux-systemd"></a>

### Linux: systemd

Чтобы включить сохранение аварийных дампов при запуске Angie как службы **systemd**
(например, при [установке из пакетов](https://angie.software//angie/docs/installation/index.md#install-packages)),
измените [настройки службы](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Process%20Properties)
в файле `/lib/systemd/system/angie.service`:

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

Либо обновите [глобальные настройки](https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html)
в файле `/etc/systemd/system.conf`:

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

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

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

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

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

   TIME                           PID   UID   GID SIG COREFILE  EXE
   --- |sampledateshort| 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
```

<a id="linux-manual-configuration"></a>

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

Проверьте [настройки аварийных дампов](https://man7.org/linux/man-pages/man5/limits.conf.5.html)
в файле `/etc/security/limits.conf`, при необходимости измените их:

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

Затем увеличьте лимит размера аварийного дампа с помощью [ulimit](https://man7.org/linux/man-pages/man1/ulimit.1p.html),
после чего перезапустите Angie, чтобы воспроизвести условия сбоя:

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

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

```console
$ sudo ls -al <путь к рабочему каталогу Angie>  # по умолчанию, см. /proc/sys/kernel/core_pattern
  ...
  -rw-r----- 1 root root 177662 Jul 27 11:05 core.1157
```

<a id="freebsd"></a>

### FreeBSD

Проверьте [настройки аварийных дампов](https://man.freebsd.org/cgi/man.cgi?query=sysctl.conf&sektion=5)
в файле `/etc/sysctl.conf`, при необходимости измените их:

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

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

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

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

```console
$ sudo service angie restart
```

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

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

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

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

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