Диагностический отчет. Утилита pangolin-diagnostic-tool

Описание

Утилита формирования диагностического отчета pangolin-diagnostic-tool предназначена для упрощения и ускорения сбора информации о состоянии и настройках стенда СУБД Pangolin. Информация собирается посредством запуска утилиты и передачи в нее определенных параметров сбора. Утилита на выходе формирует набор файлов, упакованный в tar.gz архив. Некоторые компоненты отчета требуют повышенных привилегий или доступов к каталогам.

Утилита представляет собой скомпилированный бинарный файл и набор .so библиотек.

Принцип работы

При запуске скрипт проверяет возможность повышения привилегий до суперпользователя:

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

Собранная информация представляется в следующих форматах:

единый текстовый лог;
набор файлов в формате CSV;
отдельные файлы отчетов sar, pg_profile, performance insights, файлы логов и конфигурационные файлы компонентов кластера.

Если у пользователя ОС, от имени которого выполняется скрипт, есть доступ к конфигурационным файлам компонентов кластера, они копируются в директорию configs отчета.

Особенности передачи следующих параметров запуска утилиты:

--logs – дополнительно копируются строки из журналов компонентов кластера, входящие в период, заданный параметрами --start_time и --end_time. Журналы сохраняются в директорию logs отчета.
--sar – дополнительно копируются файлы sar за промежуток времени, заданный параметрами --start_time и --end_time. Поскольку файлы sar ротируются раз в сутки, собраны будут файлы за те дни, которые входят в период отчета.
--pg_profile – дополнительно будут построены отчеты pg_profile между всеми соседними выборками расширения pg_profile попадающими в период, заданный параметрами --start_time и --end_time.
--perfinsights дополнительно будут собраны файлы performance insights, попадающие в период, заданный параметрами --start_time и --end_time.
--end_time – если не указан аргумент --start_time, он будет автоматически вычислен как 3 часа до --end_time.
--start_time –если не указан аргумент --end_time, он будет автоматически вычислен как 3 часа после --start_time. В случае, если не указаны оба аргумента, информация будет собрана за последние 3 часа до момента запуска утилиты.

В начале работы создается директория вида pgse_diag_out_suffix, где suffix — это текущая временная метка.

По завершении работы данная директория архивируется, а в консоль выводится путь к архиву.

Для получения данных из СУБД необходим доступ к консольной утилите psql.

Предполагается, что:

у пользователя, от имени которого запускается скрипт, есть права на использование psql;
путь к исполняемому файлу утилиты прописан в переменной окружения $PATH.

При старте выполняется проверка доступности psql. При ее отсутствии выводится сообщение, и сбор данных из СУБД не выполняется.

Внутри СУБД дополнительно проверяются права суперпользователя:

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

примечание

Для построения некоторых отчетов утилита использует модуль psycopg языка программирования Python. В будущем, для подключения к СУБД будет использоваться только этот модуль, в настоящее время необходимо иметь установленный модуль и доступ к утилите psql.

Настройка

Установка утилиты

примечание

При установке СУБД Pangolin с помощью скриптов автоматизации утилита pangolin-diagnostic-tool устанавливается автоматически и доступна в каталоге /opt/pangolin-diagnostic-tool/bin/.

Для установки вручную воспользуйтесь пакетным менеджером и поставляемым компонентом в виде rpm/deb-пакета:

Установите rpm/deb-пакет компонента pangolin-diagnostic-tool:

SberLinux, РЕД ОС, CentOS
Astra Linux
Альт СП

sudo dnf install pangolin-diagnostic-tool-{product_version}-{OS}.x86_64.rpm

sudo apt install pangolin-diagnostic-tool-{product_version}_amd64.deb

sudo apt-get install pangolin-diagnostic-tool-{product_version}-{OS}.x86_64.rpm

Пример команды:

sudo dnf install -y {path}/pangolin-diagnostic-tool-{product_version}-sberlinux9.x86_64.rpm

Где {path} – путь к директории или путь к дистрибутиву, {product_version} – версия продукта (текущая версия: 8.2.0).

Установка модуля psycopg

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

pip install psycopg

В случае отсутствия возможности установить данный модуль в ОС возможно создать виртуальное окружение с ним:

python3 -m venv ./myenv
source ./myenv/bin/activate
pip install psycopg

Примечание

Есть возможность скопировать каталог в любое другое доступное место пользователю.

Параметры запуска утилиты

Для утилиты pangolin-diagnostic-tool существуют следующие опциональные параметры запуска:

-U USER, --user USER

Параметр username для подключения к СУБД Pangolin. Значение по умолчанию: postgres.

-p PORT, --port PORT

Параметр port для подключения к СУБД Pangolin. Значение по умолчанию: 5433.

-h, --help

Выводит справку по использованию утилиты.

-H HOST, --host HOST

Параметр host для подключения к СУБД Pangolin. Значение по умолчанию: 127.0.0.1.

-d DATABASE, --database DATABASE

Параметр database для подключения к СУБД Pangolin. Значение по умолчанию: postgres.

--pgdata PGDATA

Параметр, определяющий путь к $PGDATA. Если не задан — будет произведена попытка поиска данного каталога в переменных окружения и запущенных процессах СУБД Pangolin. Значение по умолчанию отсутствует.

--pgbuser PGBUSER

Параметр username для подключения к виртуальной БД Pangolin Pooler для сбора статистики использования Pangolin Pooler. Значение по умолчанию отсутствует.

--start_time 'START TIME'

Параметр, определяющий начало периода сбора информации. Должен быть задан в формате YYYY-MM-DD HH:mm:ss. В случае, если не задан, будет вычислен как 3 часа до аргумента --end_time.

--end_time 'END TIME'

Параметр, определяющий конец периода сбора информации. Должен быть задан в формате YYYY-MM-DD HH:mm:ss. В случае, если не задан, будет вычислен как 3 часа после аргумента --start_time, если он задан, в противном случае буден равен текущему времени.

--perfinsights

Параметр, включающий сбор файлов выборок performance insights и построения html-отчета за период, заданный аргументами --start_time и --end_time.

--pg_profile

Параметр, включающий построение отчетов pg_profile за период, заданный аргументами --start_time и --end_time. Отчеты будут построены между всеми соседними выборками, входящими в период. Требует установленного и настроенного расширения pg_profile, в противном случае будет выведено сообщение, что расширение не найдено и отчеты построены не будут. База и схема, в которой установлено расширение, будет найдена автоматически.

--sar

Параметр, включающий сбор файлов sar компонента sysstat операционной системы linux за период, заданный аргументами --start_time и --end_time. Требует установленного и настроенного компонента sysstat, в противном случае файлы собраны не будут. По умолчанию файлы будут собраны из директории /var/log/sa. В случае, если на системе файлы пишутся в другую директорию, возможно указать путь до нее с помощью аргумента --sar_path.

--sar_path

Опциональный параметр, задающий произвольное расположение файлов sar.

--logs

Параметр, включающий сбор лог-файлов. По умолчанию лог-файлы не собираются.

--log_lines_count LOG_LINES_COUNT

Параметр, определяющий, сколько последних строк лог-файлов сохранить в отчет. Параметр введен для ограничения размера итогового отчета, количество строк должно быть достаточным для анализа и не слишком большим для экономии размера, как правило, достаточно 300-700 последних строк.

примечание

Данный параметр планируется к удалению в будущих версиях, вместо него следует использовать параметры --start_time и --end_time.

Значение по умолчанию: 300.

--version

Выводит версию утилиты и завершает работу.

В случае, если переданные параметры --user или --pgbuser отличаются от значений по умолчанию, утилита запросит пароль для данных пользователей. В ответ на запрос утилиты введите соответствующий пароль (пароль при вводе не отображается).

Запуск утилиты pangolin-diagnostic-tool с параметром --help отображает параметры запуска:

Вывод команды pangolin-diagnostic-tool --help

$ /opt/pangolin-diagnostic-tool/bin/pangolin-diagnostic-tool --help

usage: pangolin-diagnostic-tool.bin [-h] [-H HOST] [-p PORT] [-U USER] [-d DATABASE] [--pgbuser PGBUSER] [--logs] [--pgdata PGDATA] [--log_lines_count LOG_LINES_COUNT] [--without-password] [--version]

This is the Pangolin or PostgreSQL Diagnostics Collection Script. Some parts of script need superuser or root privileges, if the privileges are insufficientsome information cannot be collected.

optional arguments:
  -h, --help            show this help message and exit
  -H HOST, --host HOST  database server host or socket directory (default: 127.0.0.1)
  -p PORT, --port PORT  database server port (default: 5433)
  -U USER, --user USER  database user name (default: postgres)
  -d DATABASE, --database DATABASE
                        database name (default: postgres)
  --pgbuser PGBUSER     pangolin pooler user name
  --logs                collect log files
  --pgdata PGDATA       pgdata dir path
  --log_lines_count LOG_LINES_COUNT
                        count last lines of log for collecting (default: 300)
  --sar                 collect sar raw files for period
  --sar_path SAR_PATH   sar log path
  --perfinsights        collect perfinsigths report and raw files
  --pg_profile          collect pgprofile reports for period
  --without-password    option to signify a passwordless authentication method to database.
  --start_time START_TIME
                        collect period start time
                        example: "2023-01-01 12:00:00"
  --end_time END_TIME   collect period end time
                        example: "2023-01-01 13:00:00"
  --version             show program's version number and exit

Файловый состав

Файловый состав утилиты следующий:

bin/pangolin-diagnistic-tool – скрипт-оболочка для запуска утилиты. Настраивает окружение перед запуском;
bin/pangolin-diagnostic-tool.bin — основной файл, который является точкой входа и используется для запуска сбора статистики. Утилита осуществляет сбор аргументов, вывод справки и последовательный запуск модулей сбора информации. После окончания работы утилиты осуществляется архивирование отчета, вывод сообщения о завершении работы и пути до сформированного отчета;
lib/common.so — модуль общих переиспользуемых функций (печать в общий лог, создание каталогов, синтаксический анализ текста в CSV);
lib/vars.so — модуль глобальных переменных;
lib/sql.so — модуль с текстами SQL для сбора статистики из СУБД;
lib/linux_info.so — модуль сбора информации об ОС;
lib/linux_stat.so — модуль сбора статистики использования ОС;
lib/logs_collect.so — модуль сбора лог-файлов;
lib/config.so — модуль сбора конфигурационных файлов;
lib/libfe_elog.so – модуль поддержки сообщений об ошибках из драйвера libpq;
lib/dbms_info.so – модуль сбора статистики с помощью SQL из СУБД;
lib/perfinsights_collect.so – модуль сбора файлов performance insights;
lib/pg_profile_collect.so – модуль сбора отчетов pg_profile;
lib/sar_collect.so – модуль сбора файлов sar компонента sysstat операционной системы linux.

Управление

Синтаксис запуска утилиты

Запуск утилиты осуществляется с указанием полного пути:

/opt/pangolin-diagnostic-tool/bin/pangolin-diagnostic-tool [OPTION]

Где OPTION – опциональные параметры запуска, описанные в разделе «Параметры запуска утилиты».

Чтобы вызывать утилиту без полного пути, добавьте каталог /opt/pangolin-diagnostic-tool/bin/ в переменную окружения $PATH:

Временное добавление (на время текущей сессии):
```
export PATH="/opt/pangolin-diagnostic-tool/bin:$PATH"
```
Постоянное добавление (для всех новых сессий):

Добавьте строку в конец файла ~/.bashrc (для bash) или ~/.zshrc (для zsh):
```
export PATH="/opt/pangolin-diagnostic-tool/bin:$PATH"
```
Затем примените изменения:
```
source ~/.bashrc
```

После этого вызов утилиты выглядит так:

pangolin-diagnostic-tool [OPTION]

Отчет диагностики

После того, как утилита отработала, она выдаст сообщение о том, где сохранена диагностическая информация. Отчет формируется в каталоге с утилитой из префикса pgse_diag_out_ и временной метки запуска утилиты YYYYMMDD_HHmmSS, где YYYY — год, MM — месяц, DD — день, HH — часы, mm — минуты, SS — секунды. Сформированный архив с отчетом можно скопировать с удаленного хоста, например, с помощью scp:

scp postgres@{IP-Address}:/home/postgres/diagnostic_tool/pgse_diag_out_20220607_145935.tar.gz

Чтобы проверить содержимое архива его нужно распаковать:

tar -xvf ./pgse_diag_out_20220607_145935.tar.gz

Внимание!

Перед отправкой отчета нужно убедиться в отсутствии недопустимой к передаче информации, а именно:

непараметризованных запросов или значений параметров в:
- секции collect hot statements stat файла diag.log;
- секции collect slow statements stat файла diag.log;
- файле csv/dbms/hot_statements.csv;
- файле csv/dbms/slow_statements.csv;
- файле logs/postgresql-XXXXXXXX.log, где XXXXXXXX комбинация из даты и порядкового номера лог-файла.
логинов/паролей, а также иной чувствительной информации в:
- секции collect running services файла diag.log (в колонке COMMAND строка запуска процесса);
- файле csv/psaux.csv (в колонке COMMAND строка запуска процесса).
логинов/паролей (в том числе хешей паролей) в:
- конфигурационном файле config/pg_hba.conf;
- конфигурационном файле config/postgres.yml (конфигурационный файл Pangolin Manager, проверить в том числе секцию pg_hba).

Описание​

Принцип работы​

Настройка​

Установка утилиты​

Установка модуля psycopg​

Параметры запуска утилиты​

Файловый состав​

Управление​

Синтаксис запуска утилиты​

Отчет диагностики​

Описание

Принцип работы

Настройка

Установка утилиты

Установка модуля psycopg

Параметры запуска утилиты

Файловый состав

Управление

Синтаксис запуска утилиты

Отчет диагностики