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.plpgsql_enable	bool	true	postmaster	Управляет включением дополнительной функциональности отслеживания потоков данных в PL/pgSQL-функциях
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-запроса, вызвавшего изменение

Доработка

Доработка: Добавлена поддержка отслеживания потоков данных в PL/pgSQL-функциях.

Версия: 6.7.0

Поддержка отслеживания PL/pgSQL-функций

Расширение psql_data_lineage доработано для отслеживания потоков данных, возникающих при выполнении PL/pgSQL-функций.

Реализована поддержка отслеживания запросов с закешированным планом и отслеживания потоков данных между объектами базы данных как напрямую, так и через переменные plpgsql.

Особенности реализации

При анализе конструкций plpgsql установлено, что генерализация запроса с использованием ранее применявшихся механизмов невозможна. Это связано с тем, что путь выполнения может зависеть от ветвлений (IF), а также от параметров функции или состояния таблиц на момент выполнения.

По этой причине при каждом выполнении запроса, содержащего переменные plpgsql, выполняется повторный разбор дерева запроса. Такой подход соответствует типичному поведению plpgsql и позволяет избежать использования сохраненных на диске данных, которые могут не содержать актуального набора источников данных.

Потоки данных, проходящие через переменные, в статистике Data Lineage отображаются как потоки между объектами базы данных. Если переменная используется в запросе, вместо нее в Data Lineage указываются объекты базы данных, из которых эта переменная была сформирована. Промежуточные потоки, где приемником являлась переменная, в статистике не сохраняются.

Для отслеживания потоков через переменные поддерживаются категории операций:

• определение переменных, участвующих в запросе в качестве источников;
• выборка в переменные (SELECT ... INTO ...);
• присваивание переменным (:=);
• возврат значения переменной в конструкциях RETURN и RETURN QUERY.

Переменная типа record рассматривается как единый объект потока данных. Если источником является любое поле такой переменной, в качестве реальных источников фиксируются источники всех ее полей.

Например, поток (table1.col1 -> rec1.a), (table2.col2 -> rec1.b), (rec1.a -> table3.col3) в статистике Data Lineage будет эквивалентен потоку (table1.col1 -> table3.col3), (table2.col2 -> table3.col3).

Если для выходного параметра функции не задано имя, вместо undefined используется имя атрибута $return$, что исключает конфликт с пользовательскими переменными.

Дополнительно реализованы изменения:

1. Добавлена обработка RAISE EXCEPTION с блоком перехвата ошибок. Ранее такие конструкции могли приводить к некорректному состоянию стека вызовов функций в Data Lineage и отмене транзакции.
2. Сохранение информации о потоках данных для SELECT внутри функций допускается даже в случаях, когда назначение запроса невозможно определить.
3. Устранен конфликт с использованием pgaudit для роли, выполняющей запросы. Ранее в таких случаях отчет Data Lineage мог не содержать информации о target из-за вложенных запросов, фиксирующих операции DDL.

Управление

Параметр psql_data_lineage.plpgsql_enable по умолчанию имеет значение true и не требует дополнительной настройки.

При необходимости отключить обработку plpgsql выполните:

ALTER SYSTEM SET psql_data_lineage.plpgsql_enable='false';

После изменения параметра требуется перезагрузка СУБД.

Ограничения

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

Ограничения функциональности plpgsql

Для функциональности отслеживания plpgsql действуют ограничения:

• Не поддерживается отслеживание переменных, заданных через \gset. Такие переменные считаются источником типа CONST.
• RAISE NOTICE не рассматривается как источник или приемник данных.
• Не гарантируется корректная обработка EXECUTE, если текст запроса формируется из переменной.
• Существуют ограничения при использовании пользовательских типов, если переменные таких типов возвращаются из PL/pgSQL-функции.
• Для вложенных запросов может отсутствовать информация о функции-приемнике, если функция вызвана внешним SELECT, который не содержит потока данных.
• Не поддерживается обработка операций COPY.
• Возможна потеря данных при аварийном завершении процесса (kill -9), поскольку данные хранятся в shared memory.
• Для DDL-запросов максимальное количество объектов, создаваемых одним и тем же запросом без коллизии идентификаторов, ограничено значением 256.
• Функции, реализованные на языке C, не обрабатываются.

Ограничения совместимости

Расширение требует соответствия версии ядра СУБД, версии расширения, версии файлов сохраненных планов на диске.

При переносе данных Data Lineage между серверами версии продукта должны совпадать. В ином случае файлы Data Lineage игнорируются, а в журнал выводится предупреждение вида:

WARNING: ignoring invalid data in file ...

Для корректного переноса требуется также файл dl_stat.stat, который создается при остановке сервера и содержит данные из shared memory.

Установка

примечание

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

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

1. Добавьте к параметру shared_preload_libraries значение psql_data_lineage. При необходимости получения дополнительной информации о запросах (например, OID создаваемого объекта при выполнении DDL-запросов) рекомендуется также указать расширение pg_stat_statements.

   ALTER SYSTEM SET shared_preload_libraries='psql_data_lineage,pg_stat_statements';

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_lineage из shared_preload_libraries в конфигурационном файле postgresql.conf или используя команду ALTER SYSTEM с указанием списка расширений с исключенным psql_data_lineage:

   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)» документа «Руководство администратора».