Многопоточный Pangolin Pooler

warning

Компонент доступен только на операционной системе SberLinux.

Текущая версия многопоточного компонента Pangolin Pooler 1.5.6.

Описание

Pangolin Pooler (основанный на PgBouncer) - это менеджер пулов соединений, позволяющий минимизировать издержки на установку соединений к СУБД Pangolin.

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

Такая архитектура накладывает следующие ограничения:

масштабируемость ограничена одним ядром CPU;
пропускная способность снижается при росте числа клиентских подключений;
возможна полная утилизация одного ядра процессора, на котором запущен Pangolin Pooler;
при высокой нагрузке возрастает риск вытеснения бэкенд-процессов СУБД по OOM killer со стороны ОС.

Многопоточный Pangolin Pooler — это компонент, который представляется как многопоточная система управления соединениями, способная параллельно обрабатывать клиентские подключения с использованием нескольких потоков выполнения (воркеров).

Назначение

Основные назначения компонента:

увеличение пропускной способности сервиса под высокой нагрузкой;
равномерное распределение нагрузки по доступным ядрам CPU;
масштабирование обработки подключений за счет параллелизма на уровне потоков, а не процессов;
мониторинг утилизации потоков;
поддержание управляющих (control) команд без изменения их поведения;
устранение узких мест, связанных с однопоточной моделью обработки соединений.

Параллельная обработка и управление нагрузкой

Рабочие потоки Pangolin Pooler функционируют параллельно.

Входящие клиентские соединения и запросы распределяются между потоками выполнения с целью:

равномерной загрузки потоков;
минимизации времени ожидания;
эффективного использования ресурсов CPU.

Состояние каждого потока непрерывно обновляется во внутреннем хранилище статистики и используется для мониторинга распределения нагрузки, а также для выявления деградаций и отказов.

Установка

Многопоточная версия Pangolin Pooler поставляется в виде отдельного rpm/deb-пакета pangolin-pooler-mt.

Развертывание и настройка компонента pangolin-pooler-mt возможны:

вручную;
с использованием скриптов автоматизации.

Параметры многопоточности заданы по умолчанию и не требуют дополнительной настройки на этапе установки.

Ручная установка

Выполните установку пакета pangolin-pooler-mt:

sudo dnf install pangolin-pooler-mt-{version_component}-{OS}.x86_64.rpm

Пример заполненной команды:

sudo dnf install -y pangolin-pooler-mt-1.5.5-sberlinux9.x86_64.rpm

Выполните дальнейшие шаги установки аналогичные однопоточному компоненту Pangolin Pooler (начинайте с шага 2).

Автоматизированная установка

При автоматизированном развертывании СУБД необходимо использовать следующие схемы для установки многопоточного компонента:

standalone-postgresql-poolermt;
cluster-patroni-etcd-poolermt;
cluster-patroni-dcs-poolermt.

Если развертывание выполняется с помощью утилиты Pangolin Installer, то в конфигурационном файле утилиты необходимо прописать параметр pangolin_pooler_mt_enable в значении true (по умолчанию значение false).

Настройка

Конфигурирование компонента происходит аналогично однопоточному компоненту Pooler, в файле /etc/pangolin-pooler-mt/pangolin-pooler-mt.ini.

В рамках данной доработки реализованы новые параметры конфигурации:

Параметр	Описание	Значение по умолчанию	Возможные значения
`worker_count`	Определяет количество потоков-воркеров, используемых для обработки клиентских соединений	`2`	1 до 128

Дополнительно по умолчанию включен ванильный параметр so_reuseport. Возможность его отключения отсутствует.

Управление

Администрирование многопоточного Pangolin Pooler осуществляется также через административную базу данных с использованием стандартных управляющих команд исходного компонента PgBouncer.

Внешний интерфейс и поведение управляющих команд идентичны однопоточной версии и не требуют изменений со стороны администратора.

Добавляются новые команды управления для мониторинга потоков:

SHOW THREADS;
SHOW THREAD_STATS.

Все управляющие команды применяются согласованно ко всем потокам выполнения.

Мониторинг потоков

Для мониторинга состояния потоков выполнения используются административные команды.

SHOW THREADS

Команда SHOW THREADS возвращает текущее состояние каждого потока:

SHOW THREADS;

Пример вывода:

thread_id | state  | active_conns | total_requests | cpu_time_ms | uptime_s
----------+--------+--------------+----------------+-------------+----------
0         | active | 120          | 1849231        | 932182      | 3600
1         | active | 115          | 1798320        | 901442      | 3600
2         | active | 118          | 1810455        | 915331      | 3600
3         | error  | 0            | 124            | 112         | 3600

Название поля	Описание поля
`thread_id`	Уникальный идентификатор потока
`state`	Текущее состояние потока (`active`, `starting`, `error`)
`active_conns`	Количество активных клиентских соединений
`total_requests`	Общее количество обработанных запросов
`cpu_time_ms`	CPU-время, использованное потоком
`uptime_s`	Время работы потока с момента старта

Логирование

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

Особенности логирования:

лог-сообщения всех потоков записываются в единый лог-файл;
содержат сообщения однопоточной версии (в силу архитектуры, их смысл сохраняется);
каждое сообщение содержит идентификатор потока;
логирование выполняется асинхронно и не блокирует обработку клиентских соединений.

Диагностика

В случае ошибки в отдельном рабочем потоке:

Ошибка изолируется в пределах одного потока;
Поток сбрасывает все соединения и выполняет попытку перезапуска;
Остальные потоки продолжают обслуживание клиентских запросов;
Событие ошибки фиксируется в логах с указанием идентификатора потока;
Мониторинговые представления отражают деградированное состояние.

Ограничения

Не допускается одновременная установка и запуск однопоточной и многопоточной версий компонента на одном стенде. Также отсутствует возможность «обновления» однопоточной версии на многопоточную.
Использование многопоточного Pangolin Pooler для передачи значимых объемов данных в потоковом режиме не рекомендуется.

Основная причина связана с архитектурными особенностями: моделью передачи данных (например, через команду COPY) и режим работы пула (transaction pooling), который перелинковывает соединения между клиентами, чтобы минимизировать время ожидания. В этом режиме потоковая передача может нарушать основное преимущество — масштабируемость.

При необходимости использования пула для таких задач оцените альтернативные настройки, минимизирующие влияние на производительность.
При использовании сквозной аутентификации каждый из потоков запускает свое подключение для аутентификации, так как клиенты распределяются равномерно по потокам. Максимальное количество процессов auth_worker определяется параметром authentication_max_workers, максимальное значение которого рассчитывается по формуле: количество потоков баунсера, умноженное на количество баз внутри экземпляра. Так как auth_worker является системным процессом необходимо увеличить параметр max_worker_processes на значение authentication_max_workers для корректного создания остальных системных процессов.
Использование аутентификации по паролю в связке со сквозной аутентификацией на данный момент имеет ограничения. Каждый поток будет отдельно запрашивать пароль для прохождения аутентификации, что приводит к повторным запросам.
Применение изменений в файле userlist.txt, как и конфигурационных параметров, возможно только при выполнении перезагрузки компонента (restart).

Сценарии использования

Подключения распределяются по разным потокам в многопоточном Pangolin Pooler

В конфигурационном файле pangolin-pooler-mt.ini установите параметр worker_count=4:
```
vim /etc/pangolin-pooler-mt/pangolin-pooler-mt.ini
worker_count = 4
```
Выполните перезапуск компонента:
```
systemctl --user restart pangolin-pooler-mt
```
Из разных сессий откройте несколько подключений на порт pangolin-pooler-mt:
```
psql -p 6544
psql -p 6544
psql -p 6544
psql -p 6544
psql -p 6544
psql -p 6544
```
Выполните подключение к БД через порт pangolin-pooler-mt с использованием роли администратора. Введите пароль роли администратора:
```
psql -p 6544 -d pgbouncer -U pgbouncer
```
После ввода пароля соединение открыто:
```
Password for user pgbouncer:
psql (15.5, server 1.24.0/bouncer)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

pgbouncer=#
```

Выполните команду показа информации о потоках:

SHOW THREADS;

thread_id  | state  | active_connections | total_requests | uptime_s
-----------+--------+--------------------+----------------+----------
0          | active | 1                  | 379            | 125
1          | active | 2                  | 411            | 125
2          | active | 2                  | 385            | 125
3          | active | 2                  | 383            | 125
(4 rows)

Подключения в многопоточном Pangolin Pooler распределяются равномерно между потоками

В конфигурационном файле pangolin-pooler-mt.ini установите параметр worker_count=4:
```
vim /etc/pangolin-pooler-mt/pangolin-pooler-mt.ini
worker_count = 4
```
Выполните перезапуск компонента:
```
systemctl --user restart pangolin-pooler-mt
```
Создайте тестовую базу данных:
```
CREATE DATABASE test_db;
```
Создайте файл script.sql со следующим наполнением:
```
SELECT 1;
SELECT pg_sleep(3);
SELECT 2;
```

Запустите команду создания множественных подключений:

pgbench -i -s 10;
pgbench -h <IP-Address> -p 6544 -U postgres -c 100 -j 2 -T 99999 -r -P 1 -f script.sql test

Параллельно выполните подключение к БД через порт pangolin-pooler-mt с использованием роли администратора. Введите пароль роли администратора:
```
psql -p 6544 -d pgbouncer -U pgbouncer
```
После ввода пароля соединение открыто:
```
Password for user pgbouncer:
psql (15.5, server 1.24.0/bouncer)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

pgbouncer=#
```

Выполните команду показа информации о потоках:

SHOW THREADS;

Активные подключения распределены по потокам равномерно:

thread_id  | state  | active_connections | total_requests | cpu_time_ms | uptime_s
-----------+--------+--------------------+----------------+-------------+----------
0          | active | 31                 | 430            | 0           | 93
1          | active | 25                 | 402            | 0           | 93
2          | active | 24                 | 535            | 0           | 93
3          | active | 21                 | 384            | 0           | 93

Описание​

Назначение​

Параллельная обработка и управление нагрузкой​

Установка​

Ручная установка​

Автоматизированная установка​

Настройка​

Управление​

Мониторинг потоков​

SHOW THREADS​

Логирование​

Диагностика​

Ограничения​

Сценарии использования​

Подключения распределяются по разным потокам в многопоточном Pangolin Pooler​

Подключения в многопоточном Pangolin Pooler распределяются равномерно между потоками​