Инструментарий arenadata_toolkit

Дарья Барышева

При установке кластера ADB в базе данных автоматически создается схема arenadata_toolkit. Эта схема предназначена для сбора информации о работе кластера. Входящие в состав схемы таблицы позволяют просмотреть результаты проводимых по расписанию операций VACUUM/ANALYZE, данные о размещении файлов БД и другое. Кроме этого, с ADB поставляется набор взаимодействующих со схемой arenadata_toolkit скриптов, которые в автоматическом режиме (согласно настроенному расписанию) выполняют различные операции по управлению кластером.

ПРИМЕЧАНИЕ

В пользовательских БД, которые добавляются после установки ADB, схема arenadata_toolkit создается автоматически при первом запуске скрипта operation.py.

Таблицы схемы arenadata_toolkit

Входящие в состав arenadata_toolkit таблицы описаны ниже.

daily_operation

 

Таблица arenadata_toolkit.daily_operation партиционирована по месяцам и содержит информацию об операциях VACUUM и ANALYZE, проводимых над таблицами базы данных автоматически по расписанию. Содержимое таблицы обновляется ежедневно при запуске соответствующих скриптов vacuum, analyze, vacuum_analyze_pg_catalog.

Столбец Описание

schema_name

Название схемы

table_name

Название таблицы

action

Название операции. Возможные значения:

  • ANALYZE

  • VACUUM

status

Статус операции. Возможные значения:

  • SCS — успешно.

  • ERROR — с ошибкой.

time

Длительность операции (в секундах)

processed_dttm

Дата и время операции
db_files_current

 

Таблица arenadata_toolkit.db_files_current содержит актуальную на момент последнего запуска скрипта collect_table_stats информацию о файлах БД на всех сегментах кластера с привязкой к таблицам, индексам и другим объектам БД (при возможности определения таких связей). Таблица перезаписывается при каждом запуске скрипта.

Столбец Описание

oid

Внутренний идентификатор таблицы (OID)

table_name

Название таблицы

table_schema

Название схемы

type

Тип таблицы. См. pg_class.relkind

relamname

Метод доступа к таблице. См. pg_am.amname

table_parent_table

Название родительской таблицы (NULL при отсутствии). Актуально для партиций

table_parent_schema

Схема родительской таблицы (NULL при отсутствии). Актуально для партиций

table_database

Название базы данных, которой принадлежит таблица

table_tablespace

Название табличного пространства, которому принадлежит таблица

content

Номер сегмента, где физически расположен файл с данными. См. gp_segment_configuration.content

segment_preferred_role

Роль, назначенная сегменту при инициализации системы. См. gp_segment_configuration.preferred_role

hostname

Имя хоста, на котором расположен файл с данными

address

Адрес хоста, используемый для доступа к конкретному сегменту на сегмент-хосте. Может совпадать со значением hostname в системах, не использующих настройку имен хостов для каждого интерфейса (per-interface)

file

Полный путь к файлу с данными

modifiedtime

Время последней модификации файла с данными, возвращаемое системной командой stat. Значение этой временной метки изменяется при модификациях файла: например, при выполнении команд mknod, truncate, utime и write (если записано больше нуля байтов). Значение метки не изменяется при записи или установке информации об inode (владельце файла, группе, количестве жестких ссылок, режиме доступа и т.д.)

file_size

Размер файла с данными в байтах

tablespace_location

Место хранения табличного пространства в файловой системе
db_files_history

 

Таблица arenadata_toolkit.db_files_history партиционирована по месяцам и хранит историю изменений файлов БД на всех сегментах кластера с привязкой к таблицам, индексам и другим объектам БД (при возможности определения таких связей). Таблица может быть полезна для отслеживания динамики изменения размера БД. Структура таблицы полностью идентична arenadata_toolkit.db_files_current за исключением дополнительного поля collecttime, описанного ниже.

Содержимое arenadata_toolkit.db_files_history обновляется ежедневно при каждом запуске скрипта collect_table_stats (путем копирования актуальных данных из arenadata_toolkit.db_files_current). Таблица не очищается.

Столбец Описание

collecttime

Дата и время сбора информации
operation_exclude

 

Таблица arenadata_toolkit.operation_exclude содержит информацию о схемах БД, к которым не требуется применять операции VACUUM и ANALYZE при запуске соответствующих скриптов vacuum и analyze.

Столбец Описание

schema_name

Название схемы

backup

Необходимо ли, чтобы строка (запись о схеме) попадала в бэкап при использовании утилит gpbackup, gprestore и pg_dump. Значение по умолчанию — true, то есть строка будет восстановлена. Строки, автоматически добавляемые расширением arenadata_toolkit при создании таблицы (gp_toolkit, information_schema, pg_aoseg, pg_bitmapindex, pg_catalog и pg_toast), имеют значение по умолчанию false, чтобы избежать их повторного добавления при восстановлении

Скрипты для обслуживания кластера

Обзор

Скрипты, поставляемые с кластером ADB для его обслуживания, отображаются на вкладке Primary configuration страницы конфигурирования сервиса ADB. Для просмотра списка скриптов необходимо раскрыть узел Crontab → Crontab maintenance scripts в дереве конфигурационных настроек.

Список скриптов для управления кластером ADB
Список скриптов для управления кластером ADB
ВНИМАНИЕ

Если необходима настройка кастомных скриптов, используйте системный crontab (например, /etc/cron.d/custom_gpadmin) под пользователем, отличным от gpadmin. Секция Crontab → Crontab maintenance scripts в ADCM для этой цели не предназначена. В противном случае при переводе переключателя Crontab в неактивное состояние и реконфигурации ADB кастомные скрипты, добавленные через ADCM, будут удалены.

Для запуска скриптов используется планировщик cron. Запуск производится от имени системного пользователя (по умолчанию gpadmin). В интерфейсе ADCM каждый скрипт описывается в виде отдельной строки, включающей:

  • Время запуска скрипта — cron-выражение, описывающее периодичность выполнения скрипта.

  • Путь к скрипту — полный путь к скрипту. В настоящий момент используются два основных скрипта:

    • run_sql_to_gpssh.sh — передает результат выбранного SQL-запроса как bash-команду через gpssh. В качестве аргумента требуется указать путь к SQL-скрипту.

    • operation.py — Python-скрипт, который выполняет различные операции на уровне кластера ADB. Тип операции определяется первым аргументом (например, vacuum или analyze).

    Каждый из перечисленных скриптов может, в свою очередь, обращаться к иным SQL-запросам, скриптам и внутренним функциям схемы arenadata_toolkit. Все используемые bash-, Python- и SQL-скрипты хранятся в директории /home/gpadmin/<Arenadata_configs_directory_name>/, где <Arenadata_configs_directory_name> — значение конфигурационного параметра сервиса ADB Advanced → Arenadata configs directory name (по умолчанию arenadata_configs).

  • Аргументы — входные параметры, необходимые для запуска скрипта (при их наличии). Аргументы, доступные для скрипта operation.py, перечислены ниже.

Аргументы скрипта operation.py
Аргумент Описание Значение по умолчанию

Первый позиционный аргумент в списке (без alias)

Имя запрашиваемой операции:

  • vacuum_system_db

  • remove_orphaned_temp_schemas

  • vacuum

  • analyze

  • collect_table_stats

  • vacuum_analyze_pg_catalog

Описание каждой операции приведено в таблице Описание скриптов для обслуживания ADB

 — 

--loglevel

Уровень логирования. Возможные значения:

  • 2 — INFO;

  • 3 — WARNING;

  • 4 — ERROR;

  • 5 — CRITICAL.

Информацию об уровнях логирования можно получить в документации Python

2

--processes

Число процессов-обработчиков. Возможные значения: 1 — 10

10

--timelimit

Ограничение на время работы скрипта (в минутах). По истечении указанного времени скрипт доведет до конца обработку текущего объекта и остановится:

  • При операции vacuum скрипт остановится после обработки текущей таблицы.

  • При операции analyze — после обработки всей схемы.

  • При операции vacuum_system_db — после обработки системной базы данных (postgres или template1).

  • При операциях collect_table_stats, remove_orphaned_temp_schemas и vacuum_analyze_pg_catalog — после обработки базы данных.

Когда используется несколько обработчиков (через --processes), то текущих объектов может быть несколько одновременно. Скрипт дождется обработки каждого из них, а обработчики не будут брать в работу новые объекты по истечении указанного времени

 — 

--excludedb

Список БД, которые необходимо исключить из обработки — в дополнение к тем, что игнорируются скриптом operation.py по умолчанию:

  • template0

  • template1

  • postgres

 — 

--vacuum-order

Порядок, в котором команда VACUUM будет применяться к таблицам в пользовательских БД. Параметр может использоваться только при вызове операции vacuum. Возможные значения:

  • newest-first — таблицы, по которым в pg_catalog.pg_stat_last_operation нет данных о проведении операции VACUUM, будут обрабатываться первыми. Для обработки используется функция arenadata_toolkit.adb_vacuum_strategy_newest_first.

  • newest-last — таблицы, по которым в pg_catalog.pg_stat_last_operation нет данных о проведении операции VACUUM, будут обрабатываться последними. Для обработки используется функция arenadata_toolkit.adb_vacuum_strategy_newest_last.

  • Имя кастомной функции в формате <schema_name>.<function_name>. Сигнатура кастомной функции должна быть идентична двум функциям, упомянутым выше, и возвращать список строк, каждая из которых содержит имя схемы и имя таблицы. Если указанная функция отсутствует в каких-либо БД, операция VACUUM к ним не применяется, а в логе сохраняется соответствующее предупреждение. Дополнительную информацию можно получить в разделе Пример использования кастомной функции для VACUUM.

newest-first

Логи запуска скриптов сохраняются в директории /home/gpadmin/<Arenadata_configs_directory_name>/operation_log/ (для скрипта operation.py) и файле gzip_pg_log.log (для скрипта gzip_pg_log.sql). Периодичность очистки логов можно настроить с помощью конфигурационного параметра сервиса ADB Crontab → Delete old maintenance script logs. Значение параметра по умолчанию — 30 дней.

РЕКОМЕНДАЦИЯ

Вносить изменения в скрипты не рекомендуется. Однако, если для какого-либо скрипта требуется обновить время запуска либо добавить/изменить аргументы, следуйте шагам ниже:

  1. Внесите необходимые изменения в секцию Crontab → Crontab maintenance scripts на вкладке Primary configuration страницы конфигурирования сервиса ADB.

  2. Нажмите кнопку Save.

  3. Примените действие Reconfigure к сервису ADB.

Большинство скриптов так или иначе взаимодействует со схемой arenadata_toolkit. Назначение скриптов описано ниже.

Описание скриптов для обслуживания ADB
Номер Скрипт Описание Время запуска в формате HH:mm (UTC)

0

run_sql_to_gpssh.sh → gzip_pg_log.sql

Для каждого сегмента кластера архивирует CSV-логи, которые хранятся в <data_directory>/pg_log и не изменялись более 3 дней (где <data_directory> — директория с данными сегмента)

01:00

1

operation.py → vacuum_system_db

Запускает операцию VACUUM FREEZE для системных БД postgres и template1 (путем запуска vacuumdb -F)

02:00

2

operation.py → remove_orphaned_temp_schemas

Во всех пользовательских БД удаляет более не используемые временные схемы, имена которых начинаются на pg_temp_ и pg_toast_temp_

03:00

3

operation.py → vacuum

06:00

4

operation.py → analyze

11:00

5

operation.py → collect_table_stats

Для всех пользовательских БД:

  1. Собирает актуальную статистику по файлам данных в разрезе сегментов (размер, расположение и т.д.) и пытается определить связи файлов с таблицами, индексами и другими объектами БД. Для этого вызывает функцию, которая собирает информацию с помощью представления gp_toolkit.gp_db_files_current.

  2. Сохраняет полученную информацию в таблице arenadata_toolkit.db_files_current, предварительно очищая ее содержимое. Некоторые табличные столбцы могут остаться пустыми (NULL), если для файлов не определены соответствующие объекты БД на предыдущем шаге (например, oid, table_name и т.д.).

  3. Добавляет новые данные в таблицу arenadata_toolkit.db_files_history (копируя их из arenadata_toolkit.db_files_current).

21:00

6

operation.py → vacuum_analyze_pg_catalog

  • Запускает операции VACUUM и ANALYZE для схемы pg_catalog во всех пользовательских БД.

  • Записывает результат операции в таблицу arenadata_toolkit.daily_operation.

00:04

08:04

16:04

7

gzip_gpadmin_log.sh

Выполняет автоматическое сжатие файлов логов, расположенных в папке /home/gpadmin/gpAdminLogs/ и созданных более 3 дней назад

01:00

Пример использования кастомной функции для VACUUM

Ниже приведен пример использования кастомной функции, определяющей порядок, в котором должны обрабатываться таблицы пользовательских БД при выполнении операции VACUUM (см. --vacuum-order в таблице Аргументы скрипта operation.py):

  1. Создайте необходимую функцию, удовлетворяющую следующим условиям:

    • Наличие одного входного параметра типа text. При запуске скрипта operation.py в качестве этого параметра всегда передается значение VACUUM. В теле функции он может не использоваться.

    • Функция должна возвращать набор строк со столбцами table_schema (имя схемы БД) и table_name (имя таблицы БД). Это отсортированный перечень таблиц БД, к которым следует применить операцию VACUUM.

    Предположим, некие ETL-данные в тестовом окружении требуется обрабатывать операцией VACUUM в последнюю очередь. Приведенная ниже функция помещает все таблицы, названия которых начинаются с etl_staging, в конец списка, а также сортирует таблицы по имени схемы и самой таблицы в алфавитном порядке.

    CREATE OR REPLACE FUNCTION public.adb_vacuum_strategy_etl_staging(actionname text)
    RETURNS TABLE (table_schema name, table_name name)
    LANGUAGE sql
    STABLE
AS $$
    SELECT nspname, relname
    FROM pg_catalog.pg_class c
    JOIN pg_catalog.pg_namespace n ON relnamespace = n.oid
    WHERE relkind = 'r'
      AND nspname NOT IN (SELECT schema_name FROM arenadata_toolkit.operation_exclude)
    ORDER BY
        CASE WHEN relname LIKE 'etl_staging%' THEN 1 ELSE 0 END,
        nspname,
        relname;
$$
EXECUTE ON MASTER;
    ВНИМАНИЕ

    Функцию необходимо добавить во все пользовательские БД, к которым будет применяться операция VACUUM, т.е. во все БД за исключением системных (template0, template1, postgres) и тех, что опционально могут быть указаны в аргументе --excludedb скрипта operation.py.

  2. Убедитесь в работоспособности функции:

    SELECT * FROM public.adb_vacuum_strategy_etl_staging('VACUUM');

    В результате таблицы, относящиеся к ETL-данным в тестовом окружении (etl_staging_*), помещаются в самый низ списка:

       table_schema    |    table_name
-------------------+-------------------
 arenadata_toolkit | daily_operation_1_prt_other
 arenadata_toolkit | daily_operation_1_prt_p202510
 arenadata_toolkit | daily_operation_1_prt_p202511
 arenadata_toolkit | db_files_current
 arenadata_toolkit | db_files_history_1_prt_other
 arenadata_toolkit | db_files_history_1_prt_p202510
 arenadata_toolkit | db_files_history_1_prt_p202511
 arenadata_toolkit | operation_exclude
 kadb              | offsets
 public            | spatial_ref_sys
 public            | etl_staging_main
 public            | etl_staging_orders
 public            | etl_staging_products
 public            | etl_staging_users
(14 rows)

  3. В интерфейсе ADCM откройте вкладку Primary configuration страницы конфигурирования сервиса ADB.

  4. Раскройте узел Crontab → Crontab maintenance scripts в дереве конфигурационных настроек и нажмите на описание скрипта, выполняющего операцию vacuum.

    Переход к редактированию аргументов скрипта
    Переход к редактированию аргументов скрипта

  5. В открывшемся окне добавьте в конец строки аргумент --vacuum-order <schema_name>.<function_name>. Пример: --vacuum-order public.adb_vacuum_strategy_custom. Нажмите Apply.

    ВАЖНО

    Имя кастомной функции заполняется в формате <schema_name>.<function_name>, где <schema_name> — имя схемы, в которой создана функция; <function_name> — имя функции. Обратите внимание, что передача аргументов в функцию не поддерживается.
    Добавление аргумента --vacuum-order
    Добавление аргумента --vacuum-order

  6. Нажмите Save для сохранения изменений конфигурации и примените действие Reconfigure к сервису ADB.

    Сохранение изменений в конфигурации ADB
    Сохранение изменений в конфигурации ADB

  7. После запуска скрипта operation.py согласно установленному расписанию просмотрите содержимое лога, созданного в директории /home/gpadmin/<Arenadata_configs_directory_name>/operation_log/ (по умолчанию /home/gpadmin/arenadata_configs/operation_log/). В названии лога фиксируется дата и время запуска — например, 2025-11-10_10:05:01.172592.log.

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

    Обратите внимание, что порядок событий с одинаковой временной отметкой в логе может отличаться от фактического. В этом случае обратите внимание на идентификаторы процессов-обработчиков ForkPoolWorker: чем меньше номер, тем раньше начало обработки.

    Фрагмент лога по операции VACUUM
    2025-11-10 08:25:02,665: INFO: ForkPoolWorker-3: pid=3437270: DO: 'vacuum "arenadata_toolkit"."daily_operation_1_prt_p202511";' for 'adb'
2025-11-10 08:25:02,665: INFO: ForkPoolWorker-7: pid=3437279: DO: 'vacuum "arenadata_toolkit"."db_files_history_1_prt_p202511";' for 'adb'
2025-11-10 08:25:02,665: INFO: ForkPoolWorker-2: pid=3437269: DO: 'vacuum "arenadata_toolkit"."daily_operation_1_prt_p202510";' for 'adb'
2025-11-10 08:25:02,665: INFO: ForkPoolWorker-1: pid=3437268: DO: 'vacuum "arenadata_toolkit"."daily_operation_1_prt_other";' for 'adb'
2025-11-10 08:25:02,665: INFO: ForkPoolWorker-4: pid=3437272: DO: 'vacuum "arenadata_toolkit"."db_files_current";' for 'adb'
2025-11-10 08:25:02,665: INFO: ForkPoolWorker-5: pid=3437275: DO: 'vacuum "arenadata_toolkit"."db_files_history_1_prt_other";' for 'adb'
2025-11-10 08:25:02,667: INFO: ForkPoolWorker-10: pid=3437285: DO: 'vacuum "public"."etl_process_logs";' for 'adb'
2025-11-10 08:25:02,667: INFO: ForkPoolWorker-8: pid=3437281: DO: 'vacuum "arenadata_toolkit"."operation_exclude";' for 'adb'
2025-11-10 08:25:02,669: INFO: ForkPoolWorker-9: pid=3437283: DO: 'vacuum "kadb"."offsets";' for 'adb'
2025-11-10 08:25:02,665: INFO: ForkPoolWorker-6: pid=3437277: DO: 'vacuum "arenadata_toolkit"."db_files_history_1_prt_p202510";' for 'adb'
2025-11-10 08:25:02,988: INFO: ForkPoolWorker-4: pid=3437272: DONE: 'vacuum "arenadata_toolkit"."db_files_current";' for 'adb'
2025-11-10 08:25:02,990: INFO: ForkPoolWorker-9: pid=3437283: DONE: 'vacuum "kadb"."offsets";' for 'adb'
2025-11-10 08:25:03,090: INFO: ForkPoolWorker-5: pid=3437275: DONE: 'vacuum "arenadata_toolkit"."db_files_history_1_prt_other";' for 'adb'
2025-11-10 08:25:03,092: INFO: ForkPoolWorker-8: pid=3437281: DONE: 'vacuum "arenadata_toolkit"."operation_exclude";' for 'adb'
2025-11-10 08:25:03,095: INFO: ForkPoolWorker-10: pid=3437285: DONE: 'vacuum "public"."etl_process_logs";' for 'adb'
2025-11-10 08:25:03,186: INFO: ForkPoolWorker-6: pid=3437277: DONE: 'vacuum "arenadata_toolkit"."db_files_history_1_prt_p202510";' for 'adb'
2025-11-10 08:25:03,186: INFO: ForkPoolWorker-2: pid=3437269: DONE: 'vacuum "arenadata_toolkit"."daily_operation_1_prt_p202510";' for 'adb'
2025-11-10 08:25:03,196: INFO: ForkPoolWorker-1: pid=3437268: DONE: 'vacuum "arenadata_toolkit"."daily_operation_1_prt_other";' for 'adb'
2025-11-10 08:25:03,398: INFO: ForkPoolWorker-3: pid=3437270: DONE: 'vacuum "arenadata_toolkit"."daily_operation_1_prt_p202511";' for 'adb'
2025-11-10 08:25:03,431: INFO: ForkPoolWorker-7: pid=3437279: DONE: 'vacuum "arenadata_toolkit"."db_files_history_1_prt_p202511";' for 'adb'
2025-11-10 08:25:03,919: INFO: ForkPoolWorker-9: pid=3437283: DO: 'vacuum "public"."etl_temp_processing";' for 'adb'
2025-11-10 08:25:04,020: INFO: ForkPoolWorker-4: pid=3437272: DO: 'vacuum "public"."spatial_ref_sys";' for 'adb'
2025-11-10 08:25:04,123: INFO: ForkPoolWorker-10: pid=3437285: DO: 'vacuum "public"."etl_staging_main";' for 'adb'
2025-11-10 08:25:04,123: INFO: ForkPoolWorker-8: pid=3437281: DO: 'vacuum "public"."etl_staging_orders";' for 'adb'
2025-11-10 08:25:04,124: INFO: ForkPoolWorker-2: pid=3437269: DO: 'vacuum "public"."etl_staging_products";' for 'adb'
2025-11-10 08:25:04,129: INFO: ForkPoolWorker-5: pid=3437275: DO: 'vacuum "public"."etl_staging_users";' for 'adb'
2025-11-10 08:25:04,326: INFO: ForkPoolWorker-4: pid=3437272: DONE: 'vacuum "public"."spatial_ref_sys";' for 'adb'
2025-11-10 08:25:04,424: INFO: ForkPoolWorker-9: pid=3437283: DONE: 'vacuum "public"."etl_temp_processing";' for 'adb'
2025-11-10 08:25:04,526: INFO: ForkPoolWorker-2: pid=3437269: DONE: 'vacuum "public"."etl_staging_products";' for 'adb'
2025-11-10 08:25:04,526: INFO: ForkPoolWorker-5: pid=3437275: DONE: 'vacuum "public"."etl_staging_users";' for 'adb'
2025-11-10 08:25:04,641: INFO: ForkPoolWorker-8: pid=3437281: DONE: 'vacuum "public"."etl_staging_orders";' for 'adb'
2025-11-10 08:25:04,727: INFO: ForkPoolWorker-10: pid=3437285: DONE: 'vacuum "public"."etl_staging_main";' for 'adb'
    ВАЖНО

    • Если в какой-либо БД функция отсутствует, в лог записывается сообщение вида This function <schema_name>.<function_name> does not exist in the database.

    • Если аргумент --vacuum-order имеет недопустимое значение (отличное от newest-first/newest-last и при этом не содержащее точку), в лог записывается сообщение --vacuum-order parameter is only valid for vacuum action or invalid function name.

    В обоих случаях операция VACUUM не будет применяться к БД, при обработке которых зафиксированы ошибки.
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней