psql_data_lineage. Сбор информации о движении данных

Версия: 1.0.0.

В исходном дистрибутиве установлено по умолчанию: да.

Связанные компоненты: отсутствуют.

Схема размещения: public.

к сведению

Разработано СУБД Pangolin.

Расширение предназначено для сбора информации о движении данных внутри БД.

Объекты

Параметры конфигурирования расширения

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

Параметр	Тип	Значение по умолчанию	Контекст	Описание
psql_data_lineage.cluster_name	string	–	postmaster	Суффикс, добавляемый к уникальным идентификаторам; может быть использован для обеспечения уникальности идентификаторов между различными экземплярами СУБД при централизованном сборе DL
psql_data_lineage.enable	bool	off	superuser	Включение функциональности по определению потоков данных и связанной статистической информации
psql_data_lineage.max_records	integer	5000	postmaster	Максимальное количество записей о статистике уникальных запросов DL (определяется уникальным идентификатором запроса с учетом наименования объектов). Интервал допустимых значений: 1-INT_MAX/2
psql_data_lineage.exclude_databases	string	–	postmaster	Исключенные БД, по ним статистика не ведется. Параметр psql_data_lineage.exclude_databases обладает большим приоритетом, чем psql_data_lineage.include_databases
psql_data_lineage.include_databases	string	–	postmaster	Включенные БД. Статистика будет собираться по этим базам данных. Если параметр не заполнен, то данные будут собираться по всем таблицам (если переменная psql_data_lineage.exclude_databases не задана)
psql_data_lineage.stat_directory	string	pg_stat/dl_stat	postmaster	Параметр конфигурации расширения со значением по умолчанию $PGDATA/pg_stat/dl_stat указывает место, куда будут сохраняться данные, собранные расширением. Можно задать либо относительный путь (pg_stat/dl_stat) в $PGDATA, либо абсолютный путь к произвольному месту в системе

Функции

к сведению

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

psql_data_lineage_objects_meta – метаданные об объектах, участвующих в данном потоке данных.

Выходной параметр	Тип	Описание
process_id	text	Идентификатор запроса, обработанного Data Lineage (не совпадает с query_id, учитывает именования) {request_id (совпадающий с названием создаваемого файла)}
obj_oid	oid	Идентификатор объекта в рамках СУБД на момент выполнения запроса
qualified_name	text	Полное имя объекта в рамках данного потока данных {database_name}.{schema_name}.{object_name}@{cluster_suffix}
name	text	Полное имя объекта в рамках БД postgres {database_name}.{schema_name}.{object_name}
db_oid	oid	Идентификатор базы данных на момент выполнения запроса
obj_type	integer	Тип объекта*

psql_data_lineage_attributes_meta – метаданные об атрибутах объектов, участвующих в данном потоке данных.

Выходной параметр	Тип	Описание
process_id	text	Идентификатор запроса, обработанного Data Lineage (не совпадает с query_id, учитывает именования) {request_id}
obj_oid	oid	Идентификатор объекта в рамках СУБД на момент выполнения запроса
qualified_name	text	Полное имя объекта {database_name}.{schema_name}.{object_name}@{cluster_suffix}
attr_no	integer	Порядковый номер атрибута. Нумерация начинается с 1
name	text	Полное имя объекта {database_name}.{schema_name}.{object_name}.{attribute_name}
attr_type	oid	Тип объекта*

psql_data_lineage_objects – определение потока данных, включая источники/приемники запроса, а также статистическую информацию о потоках.

Выходной параметр	Тип	Описание
qualified_name	text	Идентификатор. Через этот идентификатор происходит связывание со всеми остальными предоставляемыми данными. Идентификатор формируется на основе идентификатора запроса расширенного метаинформацией ({request_id}/{stream_number}@{cluster_suffix}). Номер потока разделяет потоки в рамках одного запроса. Такие потоки появляются в запросах MERGE, в запросах содержащих CTE с RETURNING, при наличии функции
last_time	timestamp with time zone	Время начала последнего исполнения запроса
input_type	integer	Тип объекта источника*
input_oid	oid	Идентификатор объекта источника (пустой при const)
output_type	integer	Тип объекта приемника*
output_oid	oid	Идентификатор объекта приемника
query_plan	text	Текст последнего исполненного плана
query_text	text	Генерализованный текст запроса
first_time	timestamp with time zone	Время начала первого исполнения запроса
exec_duration	double precision	Длительность последнего исполнения запроса
exec_count	integer	Количество успешных исполнений запроса с начала сбора статистики
count_row	bigint	Суммарное количество строк, обработанных запросом с начала сбора статистики
query_id	text	Идентификатор запроса в рамках БД postgres
parent_process_id	text	Идентификатор родительского запроса, обработанного Data Lineage (не совпадает с query_id, учитывает именования). Запросы могут иметь вложенный характер. Это поле позволяет отследить цепочку вызовов. Для порождающего запроса в качестве родительского указывается он сам
process_id	text	Идентификатор запроса, обработанного Data Lineage (не совпадает с query_id, учитывает именования)

psql_data_lineage_attributes – информация о движении данных на уровне атрибутов.

Выходной параметр	Тип	Описание
qualified_name	text	Идентификатор потока данных уровня атрибутов {request_id}/{stream_number}${source_attribute_number}${source_oid}${target_attribute_number}@{cluster_suffix}
input_type	integer	Тип объекта источника*
input_oid	oid	Идентификатор объекта источника
input_attno	integer	Номер атрибута источника
output_attno	integer	Номер атрибута приемника
query	text	Идентификатор потока для связи с данными из psql_data_lineage_objects {request_id}/{stream_number}@{cluster_suffix}

psql_data_lineage_freeze_data – создает файл dl_freezed_stat.stat собранных данных, по которой выполняются все операции просмотра в текущем процессе (до отмены/удаления).

Тип результата	Описание
integer	Количество замороженных записей

psql_data_lineage_reset_freezed – консистентно обновляет замороженные данные, созданные функцией psql_data_lineage_freeze_data. У старых объектов пересчитываются exec_count и rowsCount, новые объекты добавляются.

Тип результата	Описание
integer	Количество обновленных записей

psql_data_lineage_restore_freezed – отменяет заморозку: удаляет файл dl_freezed_stat.stat данных и возвращает сбор статистики в реальном времени.

Тип результата	Описание
boolean	Успех выполнения

psql_data_lineage_reset – неконсистентно очищает общую память от накопленных статистических данных и удаляет файлы, хранящие информацию о потоках данных.

Тип результата	Описание
boolean	Успех выполнения

psql_data_lineage_clean(keep_interval TEXT) – неконсистентно удаляет данные о потоках, старше заданного keep_interval.

Тип результата	Описание
integer	Количество удаленных записей

примечание

* – все возможные типы отношений из pg_class (однако на практике индексы не участвуют в потоках данных, поэтому не могут попасть в качестве значения в это поле):

• r – обычная таблица;
• i – индекс (index);
• S – последовательность (sequence);
• v – представление (view);
• m – материализованное представление (materialized view);
• c – составной тип (composite);
• t – таблица TOAST;
• f – сторонняя таблица (foreign).

Дополнительно введенные типы:

• T – временная таблица;
• P – параметр;
• C – константа;
• F – функция.

Представления

psql_dl_stats_with_meta показывает статистику метаданных об объектах, участвующих в данном потоке данных. psql_dl_stats_with_meta состоит из следующих столбцов:

Имя столбца	Тип	Описание
qualified_name	text	Идентификатор. Через этот идентификатор происходит связывание со всеми остальными предоставляемыми данными
process_id	text	Идентификатор запроса, обработанного Data Lineage (не совпадает с query_id, учитывает именования)
parent_process_id	text	Идентификатор запроса, обработанного Data Lineage (не совпадает с query_id, учитывает именования). Запросы могут иметь вложенный характер. Это поле позволяет отследить цепочку запросов, вызывавших друг друга. Для порождающего запроса в качестве родительского указывается он сам
query_id	text	Идентификатор запроса в рамках БД postgres
input	text	Источник происхождения атрибута
output	text	Результат преобразования атрибута
first_time	timestamp with time zone	Время начала первого исполнения запроса
last_time	timestamp with time zone	Время начала последнего исполнения запроса
query_plan	text	Текст последнего исполненного плана
query_text	text	Генерализованный текст запроса
exec_duration	double precision	Длительность последнего исполнения запроса
exec_count	integer	Количество успешных исполнений запроса с начала сбора статистики
count_row	bigint	Суммарное количество строк, обработанных запросом с начала сбора статистики

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

Имя столбца	Тип	Описание
qualified_name	text	Полное имя атрибута в рамках данного потока данных
input	text	Источник происхождения атрибута
output	text	Результат преобразования атрибута
query_text	text	Текст SQL-запроса, вызвавшего изменение

Ограничения

В одной транзакции можно использовать не более 255 уникальных ID-запросов для DDL-запросов, которые имеют одинаковый инициализирующий запрос. Далее ID-запросы могут повторяться.

Установка

примечание

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

Для включения и настройки функциональности выполните шаги:

1. Добавьте к параметру shared_preload_libraries значение psql_data_lineage:

   ALTER SYSTEM SET shared_preload_libraries='psql_data_lineage';

2. Перезагрузите СУБД.

3. Выставьте параметр конфигурации psql_data_lineage.enable в БД postgres в значение on:

   ALTER SYSTEM SET psql_data_lineage.enable='on';

4. Создайте расширение:

   CREATE EXTENSION IF NOT EXISTS psql_data_lineage;

Отключение расширения

Для отключения функциональности:

1. Удалите расширение:

   DROP EXTENSION psql_data_lineage;

2. Сбросьте значение параметра psql_data_lineage.enable (верните значение off):

   ALTER SYSTEM RESET psql_data_lineage.enable;

3. Уберите значение psql_data_linenage из shared_preload_libraries в конфигурационном файле postgresql.conf или используя команду ALTER SYSTEM с указанием списка расширений с исключенным psql_data_linenage:

   ALTER SYSTEM SET shared_preload_libraries='список расширений';

4. Перезагрузите СУБД.

5. Удалите каталог, заданный параметром psql_data_lineage.stat_directory:

   rm -rf {каталог psql_data_lineage.stat_directory}

Настройка

1. Настройте список БД, для которых будет собираться статистика. Для этого реализованы параметры psql_data_lineage.exclude_databases и psql_data_lineage.include_databases. По умолчанию статистика собирается для всех БД, так как по умолчанию в значении параметров пустая строка. Изменение любого из параметров требует перезагрузки СУБД.

   Примеры использования:

   • ALTER SYSTEM SET psql_data_lineage.exclude_databases='dl_1,dl_2,dl_3' – сбор статистики по всем существующим БД в сущности СУБД кроме dl_1, dl_2, dl_3;
   • ALTER SYSTEM SET psql_data_lineage.include_databases='dl_3,dl_4,dl_5' – сбор статистики только в БД dl_3, dl_4, dl_5.

   Указание dl_3 для обоих параметров возможно, но в таком случае статистика будет собираться только в БД dl_4, dl_5.

2. Перезагрузите СУБД для применения параметров.

3. Настройте путь к месту сохранения файлов со статистикой:

   • Пример использования при сохранении данных вне $PGDATA (рекомендовано):

     1. Создайте директорию в необходимом месте:

        mkdir -p /opt/example_info/dl_stat_new

     2. Переопределите параметр psql_data_lineage.stat_directory:

        ALTER SYSTEM SET psql_data_lineage.stat_directory='/opt/example_info/dl_stat_new';

     3. Перезагрузите СУБД для применения параметра. После применения параметра путь сохранения файлов статистики будет: /opt/example_info/dl_stat_new.

   • Пример использования при сохранении в пределах $PGDATA:

     1. Создайте директорию в $PGDATA:

        mkdir -p $PGDATA/new_info/dl_stat_example

     2. Переопределите параметр psql_data_lineage.stat_directory:

        ALTER SYSTEM SET psql_data_lineage.stat_directory='new_info/dl_stat_example';

     3. Перезагрузите СУБД для применения параметра. После применения параметра путь сохранения файлов статистики будет: $PGDATA/new_info/dl_stat_example.

Использование расширения

С примерами использования расширения можно ознакомиться в подразделе «Сценарии использования» раздела «Механизм сбора информации о движении данных (Data Lineage)» документа «Руководство администратора».