Руководство по системному администрированию#

Аннотация#

Настоящий документ представляет собой руководство по системному администрированию программного компонента Веб-сервер и обратный прокси-сервер SynGX (SNGX) из состава программного продукта Platform V SynGX (SNX). Программный компонент Веб-сервер и обратный прокси-сервер SynGX (далее - SynGX) является системным программным обеспечением (СПО).

Руководство содержит сценарии администрирования SynGX, а также описание событий системного журнала и мониторинга.

Термины и определения#

Сценарии администрирования#

Администрирование#

Подключение к VM (VM - виртуальная машина), на которых установлен Продукт SynGX, для выполнения действий администрирования, должно осуществляться по протоколу SSH с использованием SSH-ключей.

Администрирование проводится от имени пользователя syngx, созданного ранее при установке SynGX.

Перечень доступных стандартных сценариев администрирования SynGX:

• Запуск SynGX;

• Остановка SynGX;

• Перезапуск SynGX;

• Изменение конфигурации SynGX;

• Проверка корректности конфигурации с точки зрения SynGX;

• Обновление версии SynGX (см. Руководство по установке);

• Удаление SynGX (см. Руководство по установке);

• Получение логов (см. раздел События системного журнала);

• Получение метрик (см. раздел События мониторинга).

В случае необходимости, можно запрашивать консультацию и рекомендации у группы сопрвождения SynGX по техническим и иным вопросам по Продукту.

Описание основных сценариев администрирования#

В данном разделе будут описаны основные сценарии администрирования - запуск, остановка и перезагрузка конфигурации Продукта.

Предполагается, что SynGX уже установлен на сервере и произведена первичная настройка конфигурации Продукта.

Запуск SynGX

Убедится что syngx не запущен (ps -ef | grep syngx), можно произвести запуск SynGX (варианты на выбор):

• Запуск с базовой конфигурацией SynGX:

$ syngx

• Запуск SynGX с отличной от базовой конфигурацией:

$ syngx -c /<путь к требуемому конфигурационному файлу>

• Запуск SynGX с использованием команды systemctl:

$ systemctl start syngx.service

Тем самым, будет произведен запуск SynGX.

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

$ systemctl enable syngx.service

Управление SynGX

Когда SynGX запущен, им можно управлять, вызывая исполняемый файл с параметром -s. Ниже показан базовый синтаксис:

syngx -s сигнал

Флаг -s отправляет сигнал главному процессу SynGX.

Вместо «сигнал» нужно подставить одно из следующих значений для управления процессом SynGX:

• stop — быстрое завершение работы SynGX: немедленно завершает все процессы SynGX, останавливает обслуживание полученных запросов;

• quit — плавное завершение работы SynGX: останавливает процессы SynGX после завершения обработки полученных до команды запросов;

• reload — перезагрузка (применение) конфигурации: позволяет применить новую конфигурацию без остановки работы SynGX. Запросы, которые были получены до перезагрузки SynGX, будут обрабатываться согласно старой конфигурации, а новые запросы - согласно новой конфигурации.

Как происходит перезагрузка конфигурационного файла: получив соответствующий сигнал, главный процесс проверяет правильность синтаксиса нового конфигурационного файла и пытается применить конфигурацию, содержащуюся в нем. Если это ему удается, главный процесс запускает новые рабочие процессы и отправляет сообщения старым рабочим процессам требование завершиться. Если не получается применить новую конфигурацию, главный процесс откатывает изменения и продолжает работать со старой конфигурацией. Старые рабочие процессы, получив команду завершиться, прекращают принимать новые запросы и продолжают обслуживать текущие запросы до тех пор, пока все такие запросы не будут обслужены. После чего старые рабочие процессы завершаются.

Подключение динамических модулей SynGX#

В SynGX часть модулей подключается динамически. Это означает, что для их включения требуется произвести дополнительные действия после установки SynGX.

Ниже представлен список модулей с динамическим подключением:

Необходимые действия для подключения динамического модуля:

1. (опционально; пройти этот шаг 1, если требуется установка динамических модулей ngx_http_lua_module либо ngx_stream_lua_module) Установить и добавить в конфигурационный файл SynGX (файл с расширением .conf) модуль ndk_http_module (контекст main). Без него подключить модуль ngx_http_lua_module либо ngx_stream_lua_module будет нельзя!

   • Для установки модуля ndk_http_module в командной строке необходимо выполнить команду (пример команды): $sudo yum install ndk_http_module.rpm .

   • После чего в конфигурационном файле SynGX (файл с расширением .conf) требуется добавить директиву с указанием пути к файлу ndk_http_module.so (контекст main). Пример задания директивы: load_module /opt/syngx/modules/ndk_http_module.so .

2. Установить модуль(-и) из RPM-пакета(-в) и добавить в конфигурационный файл (файл с расширением .conf) директиву(-ы) подключения модуля(-ей) (контекст main):

   • установить требуемый(-ые) динамический(-ие) модуль(-и). Для этого нужно для каждого модуля выполнить команду $sudo yum install {module_name}.rpm. Где {module_name} - название модуля (см. в таблице выше, названия динамических модулей SynGX даны в скобках);

   • после чего в конфигурационном файле SynGX (файл с расширением .conf) требуется добавить директиву(-ы) с указанием пути(-ей) к файлу(-ам) динамических модулей (контекст main). Пример задания директивы: load_module /opt/syngx/modules/{module_name}.so .

3. После выполнения действий в шаге 2 необходимо выполнить перезагрузку конфигурационного файла SynGX сигналом reload.

Пример указания динамических модулей в конфигурационном файле SynGX (часть конфигурации SynGX):

Настройка активной проверки работоспособности узлов (active healthcheck)#

Активная проверка работоспособности узлов заключается в том, что SynGX с заданной периодичностью отправляет запросы на узлы в группе балансировки и в зависимости от ответа считает их активными или недоступными. Если сервер не доступен, он исключается из балансировки. Запросы клиента на него не проксируются.

Функционал активного healthcheck предоставляют модули ngx_stream_upstream_check_module и nginx_upstream_check_module:

Для настройки активной проверки работоспособности на уровне секции http (L7 уровень модели OSI) с помощью модуля nginx_upstream_check_module и/или на уровне секции stream (L4 уровень модели OSI) с помощью модуля ngx_stream_upstream_check_module необходимо добавить директиву check в контекст директивы upstream.

Результаты активной проверки работоспособности узлов могут использоваться для следующих алгоритмов балансировки:

• Round Robin;

• Least Connections;

• Hash;

• IP Hash.

Для информации: узел (server) в секции upstream - это peer в терминологии модуля.

Параметры директивы check:

• interval (milliseconds) - интервал опроса узлов в группе балансировки;

• fall (count) - количество неуспешных запросов, чтобы считать, что узел не доступен;

• rise (count) - количество успешных запросов, чтобы включить узел в балансировку;

• timeout (milliseconds) - timeout для запроса к узлу;

• default_down (true/false) - статус узла по умолчанию. true - узел не доступен для балансировки, false - узел доступен для балансировки (опционально);

• port (число) - указывает порт узла, который отличается от заданного в конфигурации в директиве server. Значением по умолчанию является 0, что означает, что порт такой же, как в директиве server.

• type (строка) - указывает необходимый тип проверки работоспособности. Возможные значения: для http - tcp, ssl_hello, http, https; для stream - udp, tcp, http, ssl_hello, tcp_tls.

Описание типов проверки:

Примечание: описание директив см. ниже.

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

http {
    upstream <название кластера> {
        # simple round-robin
        server <ip-адрес узла>:<port>;
        server <ip-адрес узла>:<port>;
        check interval=3000 rise=2 fall=5 timeout=5000 default_down=true type=tcp;
    }
    server {
        listen 522;
        proxy_pass <название кластера>;
    }
    ...
}

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

stream {
    upstream <название кластера> {
        # simple round-robin
        server <ip-адрес узла>:<port>;
        server <ip-адрес узла>:<port>;
        check interval=3000 rise=2 fall=5 timeout=5000 default_down=true type=udp;
    }
    server {
        listen 522;
        proxy_pass <название кластера>;
    }
    ...
}

Дополнительные директивы, необходимые для разных типов проверки:

Описание дополнительных директив: (каждая прописывается в отдельной строке)

• check_http_send (string; Default для типов проверки http, https: "GET / HTTP/1.1\r\nHost: <имя хоста>\r\nConnection: close\r\nsyngx-http-active-healthcheck: true\r\n\r\n", Default для остальных типов: ""). Эта инструкция может настроить контент запроса, отправленный модулем. Если строка для tcp типа не задана - будет произведена попытка установить соединение с узлом в группе балансировки, но запрос отправляться не будет; установление соединения будет означать успешное прохождение проверки.

• check_http_expect_alive (syntax: [ http_2xx | http_3xx | http_4xx | ⁣http_5xx ]; Default: http_2xx | http_3xx). Задает коды ответа, которые будут означать успешность прохождения проверки.

• check_send (string; Default для типа проверки http: "GET / HTTP/1.1\r\nHost: <имя хоста>\r\nConnection: close\r\nsyngx-stream-active-healthcheck: true\r\n\r\n", Default для остальных типов: ""). Эта инструкция может настроить контент запроса, отправленный модулем. Если строка для tcp типа не задана - будет произведена попытка создать соединение с узлом в группе балансировки, но запрос отправляться не будет; установление соединения будет означать успешное прохождение проверки.

• check_expect_alive (string; Default: none). Строка для сравнения успешного состояния ответа. Сравнение ответа с параметром происходит по минимальной длине. Если параметр не указан, то строка ответа не сравнивается и запрос считается успешным.

• check_keepalive_requests (request_num; Default: 1). Эта инструкция может настроить количество запросов, до которого соединение с upstream сервером не закрывается. Значение по умолчанию составляет 1, что означает, что соединение отключается после того, как NGINX завершает 1 запрос.

Дополнительные директивы для поддержки запросов active healthcheck по TLS

Если требуется поддержка TLS, нужно выпустить SSL сертификаты и добавить параметры в конфигурацию. Каждая директива прописывается в отдельной строке.

• snx_ahc_ssl_certificate (файл; Default: none). Задаёт файл с сертификатом в формате PEM для аутентификации на upstream HTTPS-сервере. Можно использовать переменные.

• snx_ahc_ssl_certificate_key (файл; Default: none). Задаёт файл с секретным ключом в формате PEM для аутентификации на узле в группе балансировки. Вместо файла можно указать значение engine:имя:id (1.7.9), которое загружает ключ с указанным id из OpenSSL engine с заданным именем. Можно использовать переменные.

• snx_ahc_ssl_ciphers (шифры; Default: snx_ahc_ssl_ciphers DEFAULT). Описывает разрешенные шифры, которые будут использоваться при отправке запроса health check к узлу в группе балансировки. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL. Полный список можно посмотреть с помощью команды «openssl ciphers».

• snx_ahc_ssl_name (имя; Default: snx_ahc_ssl_name $peer_name). Позволяет переопределить имя сервера, используемое при проверке сертификата узла в группе балансировки, а также для передачи его через SNI при установлении соединения с узлов в группе балансировки. По умолчанию используется имя хоста из URLа upstream сервера.

• snx_ahc_ssl_protocols (TLSv1.2/TLSv1.3; Default: TLSv1.2). Разрешает указанные протоколы для запросов к узлу в группе балансировки.

• snx_ahc_ssl_server_name (on/off; Default: off). Разрешает или запрещает передачу имени сервера через расширение Server Name Indication протокола TLS (SNI, RFC 6066) при установлении соединения с узлов в группе балансировки.

• snx_ahc_ssl_trusted_certificate (файл; Default: -). Задаёт файл с доверенными сертификатами CA в формате PEM, используемыми при проверке сертификата узла в группе балансировки.

• snx_ahc_ssl_verify (on/off; Default: off). Включает или выключает проверку сертификата узла в группе балансировки.

• snx_ahc_ssl_verify_depth (число; Default: 1). Устанавливает глубину проверки в цепочке сертификатов узла в группе балансировки…

• snx_ahc_ssl_conf_command (имя значение; Default: -). Задаёт произвольные конфигурационные команды OpenSSL при установлении соединения с узлов. На одном уровне может быть указано несколько директив snx_ahc_ssl_conf_command.

• snx_ahc_ssl_crl (файл; Default: -). Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при проверке сертификата узла в группе балансировки.

• check_shm_size (size; Default: 1Mb). Все проверки работоспособности узлов балансировки хранятся в общей памяти. Данная директива позволяет задать размер общей памяти.

Настройка location для получения данных по healthcheck

Пример базовой конфигурации для получения данных по healthcheck:

http {
    server {
        listen 80;
        
        # status interface
        location /hc_status {
            <вид метрик>;
        }
     ...
}

• <вид метрик> - заменить на: check_status - для метрик по healthcheck из секции http (L7 уровень модели OSI), либо l4check_status - для метрик по healthcheck из секции stream (L4 уровень модели OSI).

Формат вывода метрик задается добавлением вида (по умолчанию html):

* <вид метрик> html
* <вид метрик> json
* <вид метрик> prometheus

Пример настройки активной проверки работоспособности узлов с разными типами соединений (tcp,udp,http,ssl_hello,tcp_tls) в секции stream

...

stream {
    upstream tcp_cluster {
        # simple round-robin
        server 127.0.0.1:8010;
        server 127.0.0.1:8011;
        check interval=2000 rise=2 fall=2 timeout=3000 default_down=true type=tcp;
        check_send "HEAD / HTTP/1.0\r\nConnection: close\r\n\r\n";
        # check_send "Hello from hc stream tcp!"; для чистого tcp
        check_expect_alive "HTTP/1.1 200";
        # check_expect_alive "Ok"; для чистого tcp
    }
    upstream udp_cluster {
        server 127.0.0.1:8020;
        server 127.0.0.1:8021;
        check interval=3000 rise=2 fall=5 timeout=5000 default_down=true type=udp;
    }

    upstream http_cluster {
        server 127.0.0.1:8030;
        server 127.0.0.1:8031;
        check interval=2000 rise=2 fall=5 timeout=3000 type=http;
        check_send "HEAD / HTTP/1.1";
        check_expect_alive "HTTP/1.1 200";
    }
    upstream ssl_hello_cluster {
        server 127.0.0.1:8040;
        server 127.0.0.1:8041;
        check interval=2000 rise=2 fall=5 timeout=3000 type=ssl_hello;
    }
    upstream tcp_tls_cluster {
        server 127.0.0.1:8050;
        server 127.0.0.1:8051;
        check interval=2000 rise=2 fall=5 timeout=3000 type=tcp_tls;
        check_send "HEAD / HTTP/1.0\r\n\r\n";
        # check_send "Hello from hc stream tcp!"; для чистого tcp
        check_expect_alive "HTTP/1.1 200";
        # check_expect_alive "Ok"; для чистого tcp

        snx_ahc_ssl_certificate           /home/syngx/syngx/ssl_src/client.crt;
        snx_ahc_ssl_certificate_key       /home/syngx/syngx/ssl_src/client.key;
        snx_ahc_ssl_trusted_certificate   /home/syngx/syngx/ssl_src/ca.crt;
        snx_ahc_ssl_verify on;
        snx_ahc_ssl_server_name on;
        snx_ahc_ssl_name sbt-ouiefs-6545.vm.mos.cloud.sbrf.ru;
        snx_ahc_ssl_protocols TLSv1.2;
        snx_ahc_ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
    }

    server {
        listen 8101;
        proxy_pass tcp_cluster;
    }
    server {
        listen 8102 udp;
        proxy_pass udp_cluster;
    }
    server {
        listen 8103;
        proxy_pass http_cluster;
    }
    server {
        listen 8104;
        proxy_ssl_certificate           /home/syngx/syngx/ssl_src/client.crt;
        proxy_ssl_certificate_key       /home/syngx/syngx/ssl_src/client.key;
        proxy_ssl_trusted_certificate   /home/syngx/syngx/ssl_src/ca.crt;
        proxy_ssl_session_reuse on;
        proxy_ssl_verify on;
        proxy_ssl_server_name on;
        proxy_ssl_name sbt-ouiefs-6545.vm.mos.cloud.sbrf.ru;
        proxy_ssl_protocols TLSv1.2;
        proxy_ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        proxy_pass ssl_hello_cluster;
    }
    server {
        listen 8105;
        proxy_ssl_certificate           /home/syngx/syngx/ssl_src/client.crt;
        proxy_ssl_certificate_key       /home/syngx/syngx/ssl_src/client.key;
        proxy_ssl_trusted_certificate   /home/syngx/syngx/ssl_src/ca.crt;
        proxy_ssl_session_reuse on;
        proxy_ssl_verify on;
        proxy_ssl_server_name on;
        proxy_ssl_name sbt-ouiefs-6545.vm.mos.cloud.sbrf.ru;
        proxy_ssl_protocols TLSv1.2;
        proxy_ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        proxy_pass tcp_tls_cluster;
    }
}

http {
    server {
        listen 8999;
        location /status_html {
            l4check_status html;
        }
        location /status_json {
            l4check_status json;
        }
        location /status_prometheus {
            l4check_status prometheus;
        }
    }
}

Более подробно можно изучить в документе Программа и методика испытаний в сценарии проверки «Active healthcheck для TCP, UDP, HTTP, HTTPS, TCP TLS (модули ngx_stream_upstream_check_module, nginx_upstream_check_module)».

Медленный старт (slow start) узла при введении в балансировку#

Функция медленного старта (slow start) заключается в плавном увеличении веса узла, который ранее с помощью активной проверки работоспособности был выведен из балансировки, а затем введен снова, с 0 до номинального значения в течение заданного времени.

Как включить медленный старт на SynGX

Пример конфигурации:

upstream backend_servers {
    server <адрес сервера1>:<port>;
    server <адрес сервера2>:<port> slow_start=30s;       
    server <адрес сервера3>:<port> slow_start=120s;
}

Примечание: slow start работает только в секции http.

Параметр slow_start - задает время, в течение которого вес сервера восстановится от нуля до своего номинального значения в ситуации, когда неработоспособный/недоступный сервер вновь становится работоспособным/доступным. Значение по умолчанию равно нулю и означает, что медленный старт выключен.

Важно: параметр нельзя использовать совместно с методами балансировки нагрузки hash, ip_hash и random.

Мониторинг работы SynGX#

Администратору SynGX необходимо периодически производить проверку и осуществлять просмотр:

• системных метрик сервера и SynGX (подробнее - см. ниже в разделе События мониторинга);

• метрик работоспособности и статистики обработки запросов (подробнее - см. ниже в разделе События мониторинга);

• журналов событий - error.log и access.log (подробнее - см. ниже в разделе События системного журнала).

Администратору сервера нужно периодически проверять значения системных метрик SynGX и утилизации ресурсов сервера компонентом SNGX, чтобы они не превышали допустимых пороговых значений согласно нормам эксплуатирующей организации.

При превышении пороговых значений, администратору нужно оперативно выявить причину повышенной нагрузки путем анализа значений различных системных метрик, метрик мониторинга SynGX, логов компонента SNGX, и предпринять необходимые действия для решения проблемы в соответствии с порядком разбора инцидентов АС (руководствоваться внутренним регламентом, порядком и нормами эксплуатирующей организации).

В случае неуспешности предпринятых действий, можно прибегнуть к перезагрузке либо остановке процессов SynGX на сервере. После чего произвести запуск в соответствии с Руководством по установке и Руководством по системному администрированию.

События системного журнала#

SynGX, как и Nginx, имеет возможность вести два вида журналов. В первый журнал, который называется error.log, SynGX записывает информацию о своей собственной работе. Количество информации, которая записывается в error.log, определяется в конфигурации SynGX, при этом формат журнала изменять нельзя. Во второй журнал, который называется access.log, SynGX записывает информацию об обработанных запросах клиентов. Формат сообщений, которые записываются в данный журнал, определяется в конфигурации SynGX.

Логгирование можно настроить в конфигурационном файле SynGX с расширением .conf, который по умолчанию располагается в директории /opt/syngx/conf. Конфигурацию задает администратор SynGX самостоятельно, согласно требованиям эксплуатирующей организации.

Журнал error log

В error log записываются сообщения об ошибках, возникающих в процессе работы сервиса, предупреждения, информационные сообщения, отладочные сообщения - в зависимости от выставленного уровня логгирования. Запись производится по следующей маске: время события, уровень события, номер процесса, сообщение по событию.

Настройка error log производится директивой error_log в конфигурационном файле с расширением .conf (по умолчанию syngx.conf).

Синтаксис:	error_log файл [уровень];

,где [уровень] - это выставляемый уровень логгирования журнала.

Основные типы (уровни) событий системного журнала:

• Error — ошибки, возникающие в процессе работы сервиса;

• Warn — предупреждения, возникающие в процессе работы сервиса;

• Info — информационные сообщения, возникающие в процессе работы сервиса;

• Debug — отладочные сообщения (детали взаимодействия с внешними системами), возникающие в процессе работы сервиса.

Подробнее про настройку директивы error log можно изучить на странице сайта Nginx: https://nginx.org/ru/docs/ngx_core_module.html#error_log .

Пример сообщения об ошибке:

2022/10/30 16:29:36 [error] 3923#3923: *63024022 connect() failed (111: Connection refused) while connecting to upstream, client: <ip-адрес клиента>, server: , request: "POST /hc_proxy/healthcheck/service-healthcheck/ufs-delivery-proxy HTTP/1.0", upstream: "https://<ip-адрес узла>:<port>/healthcheck/service-healthcheck/ufs-delivery-proxy"

Поскольку в SynGX события типа error записывает Nginx, подробнее про события данного типа, записываемые в error log, можно изучить по ссылке сайта Nginx: https://docs.nginx.com/nginx/admin-guide/monitoring/logging/ .

Журнал access log

В access.log ведется запись логов запросов в указанном формате. Логи записываются в контексте location’а, где заканчивается обработка.

Настройка access.log производится директивой access_log в конфигурационном файле с расширением .conf (по умолчанию syngx.conf).

Подробнее про настройку директивы access_log можно изучить на странице сайта Nginx: https://nginx.org/ru/docs/http/ngx_http_log_module.html#access_log .

Дополнительная информация по системному журналу

По умолчанию, настроенные администратором события журнала локально записываются в директорию /opt/syngx/logs/ :

• error.log;

• access.log.

SynGX позволяет писать журналы в файлы на VM, а также отправлять их по протоколу syslog, что также определяется в конфигурации SynGX. При записи журналов в файлы на VM, необходимо иметь ввиду, что в ходе работы SynGX размер журналов постоянно увеличивается, поэтому необходимо предусмотреть способ ограничения размера логов, например, с помощью ротирования логов с помощью log rotate.

При необходимости отправлять журналы на другие VM, можно использовать различные схемы с использованием дополнительного ПО, например, RSYSLOG или fluetbit. Описание настройки этих компонентов можно посмотреть в документации на указанные сторонние компоненты.

В SynGX нет функционала отправки логов по протоколу Kafka, однако прикладной разработчик может донастроить SynGX, чтобы он мог отправлять логи по данному протоколу. Например, для этих целей можно использовать RSYSLOG.

События мониторинга#

Мониторинг необходим для раннего обнаружения и локализации технологических событий прежде, чем они окажут негативное влияние на клиентов SynGX. Мониторинг позволяет в реальном времени получать объективную информации о состоянии SynGX, отслеживать статистику обработки запросов и своевременно реагировать на нештатные или не типичные ситуации в работе.

При работе SynGX необходимо отслеживать два вида метрик:

• системные метрики, к которым относятся потребление ЦПУ, использование оперативной памяти, наличие доступного дискового пространства и т.д. на VM. Системные метрики показывают, достаточно ли всем процессам, работающим в ОС на VM, ресурсов для корректной работы. Если какой-либо процесс или приложение (необязательно SynGX) в случае сбоя или ошибки начинает потреблять все доступные ресурсы, это начинает влиять на работу других процессов и приложений. С точки зрения SynGX негативное влияние будет приводить к увеличению времени обработки сетевых запросов, возникновению ошибок при установлении соединений и т.д. За получение и мониторинг системных метрик отвечают администраторы VM, на которых установлен SynGX, в соответствии с принятыми стандартами и практиками.

• метрик работоспособности и статистики обработки запросов, к которым относятся количество установленных на текущий момент соединений, количество принятых запросов, количество обработанных HTTP запросов с кодами ответов 2xx, 3xx и т.д. Эти метрики показывают, насколько успешно обрабатываются запросы клиентов SynGX с течением времени. Например, в нормальном режиме количество обработанных HTTP запросов с кодами ответов 4xx и 5xx должно быть минимальным. Если их количество начинает расти, это признак того, что в цепочке обработки запросов возникли какие-то проблемы, которые требуют устранения. Количество установленных на текущий момент соединений характеризует текущий уровень нагрузки на SynGX. Если это количество начинает расти, это может быть признаком DoS атаки. Если это количество сильно снижается, это может означать наличие сетевых проблем при обращении к серверу SynGX (например, сбой DNS сервера).

Для мониторинга своей работы SynGX предоставляет метрики работоспособности и статистику обработки запросов в ответ на HTTP REST запрос. Адрес, на который необходимо отправлять запрос, а также формат ответа (в виде JSON-структуры или текстовом виде в формате Prometheus) настраиваются в конфигурации SynGX. Пример настройки такого рода приведен в предустановленной конфигурации SynGX.

При настройке адресов, по которым будут доступны метрики, необходимо использовать существующие в SynGX механизмы обеспечения безопасности (описанные в Руководстве по безопасности):

• Настроить доступ только с использованием протокола TLS не ниже версии 1.2.

• Настроить доступ с проверкой имени и пароля пользователя.

• Настроить доступ с определенных сетевых адресов.

Возможность настроить SynGX, чтобы он самостоятельно отправлял метрики в какую-либо систему, не предусмотрена. Дополнительные метрики могут быть настроены администратором самостоятельно в конфигурации SynGX (конфигурационный файл с расширением .conf).

Полный перечень доступных метрик SynGX и способов их настройки описан ниже.

Перечень доступных метрик#

Метрики предоставляют подключенные модули SynGX - nginx-module-vts, ngx_http_extstatus_module, nginx_upstream_check_module, ngx_stream_upstream_check_module, sts (nginx-module-stream-sts, nginx-module-sts). Необходимо учесть, что некоторые модули являются динамическими, то есть, требуется их дополнительное подключение и настройка (рассмотрено в разделе «Подключение динамических модулей SynGX»).

Для доступа к конкретной группе метрик необходимо через командную строку отправить GET-запрос типа (запрос к модулю SynGX):

{ip-адрес сервера либо 127.0.0.1}/{location}

, где {location} - адрес, по которому можно получить метрики из конкретного модуля SynGX. Адрес настраивается в конфигурации SynGX.

Пример GET-запроса:

localhost:80/status_json

Далее подробно рассмотрим, какие метрики может выдавать каждый указанный модуль.

Модуль nginx-module-vts

Данный модуль предоставляет возможность получения статистики по запросам в разрезе виртуальных серверов в формате html-страницы, а также можно настроить выдачу в форматах json и prometheus. Помимо этого, рассматриваемый модуль может выдавать статистику по использованию кеша для статистического содержимого в форматах json и prometheus. Модуль обеспечивает предоставление следующих видов метрик:

• main:

  • время безотказной работы ((nowMsec - loadMsec)/1000); nowMsec, loadMsec - в миллисекундах;

• connections:

  • всего подключений и запросов (аналогично stub_status_module в NGINX);

• sharedZones:

  • информация об объеме общей памяти, используемой модулем nginx-module-vts;

• serverZones:

  • объем трафика (входящий/исходящий), количество запросов и ответов и коэффициент попадания в кеш на каждую зону сервера;

  • объем общего трафика (входящий/исходящий), количество запросов и ответов (имя зоны) и коэффициент совпадений;

• filterZones:

  • объем трафика (входящий/исходящий), количество запросов и ответов, а также коэффициент попадания в кеш для каждой зоны сервера, отфильтрованной с помощью vhost_traffic_status_filter_by_set_key директивы;

  • общий объем трафика (входящий / исходящий), количество запросов и ответов (имя зоны *) и коэффициент совпадений, отфильтрованные с помощью vhost_traffic_status_filter_by_set_key директивы .

• upstreamZones:

  • объем трафика (входящий/исходящий) и количество запросов и ответов на сервер в каждой вышестоящей группе;

  • текущие настройки (weight, maxfails, failtimeout…) в synx.conf

• cacheZones:

  • объем трафика (входящий/исходящий), размер (capacity/used) и коэффициент попаданий на каждую зону кэша при использовании директивы proxy_cache.

Пример конфигурации для получения метрик приведен ниже:

server {
 ⁣ ⁣ ⁣ ⁣listen 80;

...

 ⁣ ⁣ ⁣ ⁣⁣location /vts {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display_format html;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣}

Пример вывода метрик модуля в формате JSON:

Пример вывода метрик модуля в формате Prometheus:

Модуль ngx_http_extstatus_module

Данный модуль предоставляет возможность получения детальной статистики по HTTP-запросам в разрезе кодов HTTP-ответов в форматах json и prometheus (нужна настройка в конфигурации SynGX). Помимо этого, он может выдавать статистику по использованию TLS-соединений в форматах json и prometheus (нужна настройка в конфигурации SynGX).

Ниже приведен пример метрик в json-формате, которые выдаются при обращении к данному модулю.

{
 ⁣ ⁣"active_connection" : "2",
 ⁣ ⁣"accepts" : "6",
 ⁣ ⁣"handled" : "6",
 ⁣ ⁣"requests" : "5",
 ⁣ ⁣"reading" : "0",
 ⁣ ⁣"writing" : "1",
 ⁣ ⁣"waiting" : "1",
 ⁣ ⁣"syngx_uptime" : "67635",
 ⁣ ⁣"syngx_time" : "1664952670",
 ⁣ ⁣"responses" : {
 ⁣ ⁣ ⁣ ⁣"2xx": "2",
 ⁣ ⁣ ⁣ ⁣"3xx": "0",
 ⁣ ⁣ ⁣ ⁣"4xx": "2",
 ⁣ ⁣ ⁣ ⁣"5xx": "0",
 ⁣ ⁣ ⁣ ⁣"codes" : {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣"200": "2",
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣"403": "2"
 ⁣ ⁣ ⁣ ⁣},
 ⁣ ⁣ ⁣ ⁣"total": 4
 ⁣ ⁣},
 ⁣ ⁣"ssl" : {
 ⁣ ⁣ ⁣ ⁣"handshakes" : 0,
 ⁣ ⁣ ⁣ ⁣"handshakes_failed" : 0,
 ⁣ ⁣ ⁣ ⁣"session_reuses" : 0
 ⁣ ⁣}
}

Пример конфигурации для получения метрик приведен ниже:

server {
 ⁣ ⁣ ⁣ ⁣listen 80;

...

 ⁣ ⁣ ⁣ ⁣location /status_prometheus {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣snx_http_extstatus_prometheus on;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣allow ⁣ ⁣all;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣deny ⁣ ⁣all;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}

 ⁣ ⁣ ⁣ ⁣location /status_json {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣snx_http_extstatus_json on;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣allow ⁣ ⁣all;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣deny ⁣ ⁣all;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣}

Пример вывода метрик модуля в формате JSON:

Пример вывода метрик модуля в формате Prometheus:

Модуль nginx_upstream_check_module

Данный модуль предоставляет возможность учета текущего состояния вычислительного узла в группе балансировки на уровне секции http (на уровне L7 модели OSI) при распределении запросов. При базовой настройке конфигурации, он будет выдавать метрики в виде HTML-страницы. Однако, администратор может настроить выдачу в формате json или prometeus.

Данный модуль может отображать статусы по разным видам проверок healthcheck - tcp, ssl_hello, http, https.

Информация по настройке модуля приведена в разделе «Настройка активной проверки работоспособности узлов (active healthcheck)» выше.

Пример конфигурации для получения метрик приведен ниже:

server {
 ⁣ ⁣ ⁣ ⁣listen 80;

...

 ⁣ ⁣ ⁣ ⁣location /l7status_html {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣check_status html;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}

 ⁣ ⁣ ⁣ ⁣location /l7status_json {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣check_status json;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
        }

 ⁣ ⁣ ⁣ ⁣location /l7status_prometheus {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣check_status prometheus;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣}

Пример вывода при обращении к метрикам данного модуля в формате HTML:

Пример вывода метрик модуля в формате JSON:

.

Пример вывода метрик модуля в формате Prometheus:

Модуль ngx_stream_upstream_check_module

Данный модуль предоставляет возможность учета текущего состояния вычислительного узла в группе балансировки на уровне секции stream (на уровне L4 модели OSI) при распределении запросов. При базовой настройке конфигурации, он будет выдавать метрики в виде HTML-страницы. Однако, администратор может настроить выдачу в формате json или prometeus.

Данный модуль может отображать статусы по разным видам проверок healthcheck - udp, tcp, http, ssl_hello, tcp_tls.

Информация по настройке модуля приведена в разделе «Настройка активной проверки работоспособности узлов (active healthcheck)» выше.

Пример конфигурации для получения метрик приведен ниже:

http {
    server {
        listen 80;
        
        # status interface
        location /l4hc_status_html {
            l4check_status html;
        }

        location /l4hc_status_json {
            l4check_status json;
        }

        location /l4hc_status_prometheus {
            l4check_status prometheus;
        }
     ...
}

Пример вывода при обращении к метрикам данного модуля в формате HTML:

.

Пример вывода метрик модуля в формате JSON:

.

Пример вывода метрик модуля в формате Prometheus:

.

Модули sts (nginx-module-stream-sts, nginx-module-sts)

Описание модулей:

• nginx-module-stream-sts - данный модуль предназначен для сбора статистики на уровне L4 OSI (UDP и TCP соединения);

• nginx-module-sts - этот модуль добавляет возможность отображения статистики по запросам на уровне L4.

Модуль nginx-module-sts обеспечивает предоставление следующих видов метрик:

• main:

  • время безотказной работы ((nowMsec - loadMsec)/1000); nowMsec, loadMsec - в миллисекундах;

• connections:

  • всего подключений и запросов;

• streamServerZones:

  • информация о трафике (входящий/исходящий), количество запросов и ответов, а также соотношение статусов (1xx, 2xx…) для каждой зоны сервера;

• streamFilterZones:

  • информация об общем трафике (входящий/исходящий), количестве запросов и ответов, а также о соотношении совпадений состояния (1xx, 2xx…) для каждой зоны сервера, отфильтрованного с помощью директивы server_traffic_status_filter_by_set_key.

  • информация о трафике (входящий/исходящий), количестве запросов и ответов для <имя зоны *> и коэффициенте совпадений, отфильтрованная с помощью директивы server_traffic_status_filter_by_set_key.

• streamUpstreamZones

  • объем трафика (входящий/исходящий) и количество запросов и ответов на сервер в каждой вышестоящей группе;

  • текущие настройки (weight, maxfails, failtimeout…) в synx.conf

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

Пример базовой настройки модуля sts дан ниже:

1. Задать директиву stream на уровне директив main в конфигурационном файле SynGX (syngx.conf):

stream {
    log_format proxy '$remote_addr [$time_local] '
                     '$protocol $status $bytes_sent $bytes_received '
                     '$session_time "$upstream_addr" '
                     '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"';

    server_traffic_status_zone;
    server {
        listen <port> udp;
        access_log  /opt/syngx/logs/access_stream.log  proxy;
        proxy_requests 1;
        proxy_responses 1;
        proxy_pass <ip-адрес куда проксировать>:<port>;
    }
}

2. Добавить подключение сбора статистики на уровне директив http в конфигурационном файле SynGX (syngx.conf), добавить тестовый сервер:

http {
   # for test stream_sts module
   stream_server_traffic_status_zone;
   server {
    listen <port>;
    server_name stream_sts_module;
    location /status {
        stream_server_traffic_status_display;
        stream_server_traffic_status_display_format html;
      }
   }
}

Пример вывода метрик модуля:

Часто встречающиеся проблемы и пути их устранения#

Невозможность запуска SynGX

Возможные причины:

• наличие синтаксических ошибок в конфигурации SynGX

  • рекомендация: в данном случае администратору необходимо убедиться, что в конфигурационном файле SynGX нет синтаксических ошибок. После чего произвести запуск SynGX.

• отсутствие необходимых файлов:

  • рекомендация: администратору необходимо пройти чек-лист руководства по установке SynGX. В случае отсутствия указанных в чек-листе файлов, требуется заново пройти инструкцию по подготовке сервера и инструкцию по установке SynGX;

Зависший процесс на сервере

Рекомендация: перезапустить процесс SynGX.

Зависший процесс может привести к невозможности штатной остановки SynGX. В таком случае, потребуется применить системную команду для прекращения процессов SynGX.

Некорректная логика обработки запросов

Рекомендация: администратору необходимо проверить конфигурационный файл на предмет наличия логических ошибок в конфигурации: корректность указанных директорий, путей (locations), а также настройка выставленных директив. Также нужно убедиться, что на сервере в указанных директориях присутствуют необходимые файлы.

Проблемы (ошибки) при подключении динамических модулей

Проблема: сообщение unknown directive при запуске/при перезагрузке/при проверке конфигурационного файла SynGX.

Возможные причины:

1. отсутствие установленного и корректно добавленного в конфигурационный файл требуемого динамического модуля;

2. отсутствие библиотеки libluajit при подключении динамического модуля ngx_http_lua_module либо ngx_stream_lua_module;

3. отсутствие установленного и добавленного в конфигурационный файл модуля ndk_http_module при подключении динамического модуля ngx_http_lua_module либо ngx_stream_lua_module.

Рекомендации:

1. проверить, к какому модулю относится директива, и убедиться, что модуль установлен и корректно подключен (см. подраздел Подключение динамических модулей SynGX данного Руководства по системному администрированию);

2. при использовании динамического модуля ngx_http_lua_module либо ngx_stream_lua_module необходимо проверить наличие библиотеки libluajit. При отсутствии, ее необходимо установить согласно Руководству по установке документации SynGX;

3. при использовании динамического модуля ngx_http_lua_module либо ngx_stream_lua_module необходимо проверить установку и добавление в конфигурационный файл SynGX модуля ndk_http_module (см. подраздел Подключение динамических модулей SynGX данного Руководства по системному администрированию).