Postgres Pro Enterprise : Документация: 15: F.6. auto_dump : Компания Postgres Professional

F.6. auto_dump
Пред.	Наверх	Приложение F. Дополнительные модули и расширения, поставляемые в `postgrespro-ent-15-contrib`	Начало	След.

F.6. auto_dump

F.6.1. Установка и настройка
F.6.2. Параметры конфигурации
F.6.3. Ограничения и особенности

auto_dump — расширение Postgres Pro, предназначенное для сбора данных по длительным и проблемным запросам и последующего воспроизведения этих запросов с целью устранения неполадок.

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

операторы CREATE TABLE для временных и постоянных таблиц, на которые даётся ссылка в запросе;
операторы INSERT/COPY для заполнения таблиц данными, которые существовали на момент выполнения исходного проблемного запроса;
исходный проблемный SQL-запрос и план выполнения этого запроса, который можно сформировать с помощью команды EXPLAIN и/или EXPLAIN ANALYZE.

F.6.1. Установка и настройка

Расширение auto_dump включено в состав Postgres Pro Enterprise. Установив Postgres Pro Enterprise, выполните следующие действия, чтобы подготовить auto_dump к работе:

Добавьте auto_dump в параметр shared_preload_libraries в файле postgresql.conf:
```
shared_preload_libraries = 'auto_dump'
```
Поскольку расширение auto_dump по умолчанию отключено, включите его:
```
auto_dump.enable = on
```

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

F.6.2. Параметры конфигурации

Расширение auto_dump предоставляет следующие параметры конфигурации для настройки автоматической выгрузки запросов.

F.6.2.1. Общие параметры конфигурации

auto_dump.enable (boolean): Включает расширение. По умолчанию этот параметр отключён.
auto_dump.output_directory (string): Задаёт путь в файловой системе к каталогу, в который сохраняются файлы выгрузки таблицы. Это обязательный параметр. У пользователя операционной системы, от имени которого запущена служба, должны быть права на чтение и запись в этом каталоге.

F.6.2.2. Параметры, управляющие условиями триггеров

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

auto_dump.dump_on_query_string (string)

Определяет фрагмент SQL-запроса, нечувствительный к регистру, в качестве условия триггера. Если этот фрагмент встречается в запросе, запрос выгружается. Значение по умолчанию — пустая строка (''), что означает, что триггер для запросов не задан.

auto_dump.dump_on_cancel (boolean)

Определяет, будет ли осуществляться выгрузка запросов, отменённых СУБД, например, функцией pg_cancel_backend или по истечении времени ожидания блокировки.

Обратите внимание, что параметр auto_dump.dump_on_cancel не запускает выгрузку для сеансов, которые были прерваны из-за idle_in_transaction_session_timeout или idle_session_timeout.

По умолчанию этот параметр отключён.

auto_dump.dump_on_bad_plan (boolean)

Сравнить ожидаемое и фактическое число строк для всех запросов. Для выявления проблемных запросов используются два пороговых значения: auto_dump.bad_plan_count_threshold и auto_dump.bad_plan_percent_threshold. Триггер автоматической выгрузки срабатывает только, когда разница в числе строк превышает оба пороговых значения.

По умолчанию этот параметр отключён.

auto_dump.bad_plan_count_threshold (integer)

Задаёт условие триггера автоматической выгрузки на основе абсолютной разницы между ожидаемым и фактическим числом строк.

Анализируются все узлы плана выполнения запроса. Условие считается выполненным, если разница между ожидаемым и фактическим числом строк превышает значение этого параметра.

Если для параметра задано значение 0, условие всегда считается выполненным. Значение по умолчанию — 1000000.

auto_dump.bad_plan_percent_threshold (integer)

Задаёт условие триггера автоматической выгрузки на основе разницы между ожидаемым и фактическим числом строк в процентах. Параметр может принимать целочисленные значения от 0 до 100 (значение по умолчанию).

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

Если для параметра задано значение 0, условие всегда считается выполненным.

auto_dump.dump_on_time (boolean)

Сохранить выгрузку запроса, если время его выполнения превышает значение auto_dump.timeout. По умолчанию этот параметр отключён.

auto_dump.timeout (integer)

Задаёт значение тайм-аута для auto_dump.dump_on_time в миллисекундах. Возможные значения — положительные целые числа. Значение по умолчанию — 0. Если для параметра задано значение 0, выгружаются все запросы.

Если значения заданы для нескольких параметров, управляющих условиями триггеров, они обрабатываются в следующем порядке:

auto_dump.dump_on_cancel
auto_dump.dump_on_query_string
auto_dump.dump_on_bad_plan
auto_dump.dump_on_time

F.6.2.3. Параметры, управляющие содержанием выгрузок

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

auto_dump.dump_temporary_tables (boolean)

Записать в файл выгрузки временные таблицы сеанса, используемые текущим запросом. По умолчанию этот параметр отключён.

auto_dump.dump_persistent_tables (boolean)

Записать в файл выгрузки все постоянные таблицы, используемые текущим запросом. По умолчанию этот параметр отключён.

auto_dump.dump_all_temp_tables (boolean)

Записать в файл выгрузки все временные таблицы сеанса, включая те, которые используются текущим запросом. По умолчанию этот параметр отключён.

auto_dump.dump_data (boolean)

Записать в файл выгрузки содержимое таблиц. Если параметр отключён, выгружаются SQL-запросы только с командами для создания таблиц. Данными таблицы не наполняются. По умолчанию этот параметр отключён.

Чтобы создать SQL-файл с содержимым таблиц, включите этот параметр, а также auto_dump.dump_temporary_tables или auto_dump.dump_persistent_tables.

auto_dump.dump_indexes (boolean)

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

auto_dump.dump_copy_data (boolean)

Определяет метод выгрузки данных таблиц.

Если параметр включён, данные таблиц выгружаются с помощью команды COPY TO. В результате для каждой таблицы создаётся отдельный TXT-файл, на который даётся ссылка в операторе COPY ... FROM в файле выгрузки.

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

По умолчанию этот параметр отключён.

auto_dump.dump_query (boolean)

Записать в файл выгрузки SQL-запрос, для которого создаётся выгрузка. По умолчанию этот параметр отключён.

auto_dump.dump_create (boolean)

Записать в файл выгрузки SQL-команды для создания выгружаемых таблиц. По умолчанию этот параметр отключён.

auto_dump.dump_plan (boolean)

Записать в файл выгрузки план текущего SQL-запроса. По умолчанию этот параметр отключён.

F.6.3. Ограничения и особенности

Используйте расширение auto_dump с осторожностью. Расширение предназначено для отладки и не может использоваться для непрерывного мониторинга. Поэтому не рекомендуется настраивать auto_dump таким образом, чтобы оно выгружало каждый запрос.

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

Расширение auto_dump несовместимо с командой PREPARE TRANSACTION при работе с временными таблицами. Проверка операций с временными объектами происходит раньше проверки включённых подготовленных транзакций, из-за чего возникает ошибка, даже если max_prepared_transactions настроен правильно.
Если включён параметр auto_dump.dump_all_temp_tables, расширение auto_dump не может обратиться к временным пространствам имён из автономных транзакций. В этом случае выводится соответсвующая ошибка.
Использование расширения может отразиться на статистике производительности. Если параметр auto_dump.dump_data включён, расширение читает данные таблиц для формирования выгрузок, что искусственно увеличивает количество операций последовательного сканирования. Это приводит к неточной статистике.

Пред.	Наверх	След.
F.5. auth_delay	Начало	F.7. auto_explain

F.6. auto_dump
Prev	Up	Appendix F. Additional Supplied Modules and Extensions Shipped in `postgrespro-ent-15-contrib`	Home	Next

F.6. auto_dump

F.6.1. Installation and Configuration
F.6.2. Configuration Parameters
F.6.3. Limitations and Considerations

auto_dump is a Postgres Pro extension that is designed to collect data on long-running and problematic queries and to further reproduce these problems for troubleshooting.

To simplify reproducing problematic queries, this extension generates a dump file containing the following entities:

CREATE TABLE statements for both temporary and permanent tables referenced in the query.
INSERT/COPY statements to populate the tables with data available during the original problematic query execution.
The original problematic SQL query along with its execution plan, which can be generated by EXPLAIN, EXPLAIN ANALYZE, or both.

F.6.1. Installation and Configuration

The auto_dump extension is included into Postgres Pro Enterprise. Once you have Postgres Pro Enterprise installed, complete the following steps to enable auto_dump:

Add auto_dump to the shared_preload_libraries parameter in the postgresql.conf file:
```
shared_preload_libraries = 'auto_dump'
```
As auto_dump is disabled by default, enable it:
```
auto_dump.enable = on
```

Before using the extension, set other required configuration parameters and restart the database server for the changes to take effect.

F.6.2. Configuration Parameters

The auto_dump extension provides the following configuration parameters for managing automatic query dumping parameters.

F.6.2.1. General Configuration Parameters

auto_dump.enable (boolean): Enables the extension. This parameter is disabled by default.
auto_dump.output_directory (string): Specifies the file system path to the directory where table dump files are saved. This is a mandatory parameter. The operating system user the service runs as must have read-write permissions for this directory.

F.6.2.2. Trigger Condition Control Parameters

The following configuration parameters control the conditions that trigger automatic query dumps.

auto_dump.dump_on_query_string (string)

Specifies a case-insensitive fragment of an SQL query. If this fragment appears anywhere in a query, the query is dumped. The default is an empty string (''), which means that no query is dumped.

auto_dump.dump_on_cancel (boolean)

Controls whether a dump is triggered for queries that are canceled by the DBMS, for example, by the pg_cancel_backend function or due to a lock timeout.

Note that auto_dump.dump_on_cancel does not trigger dumps for sessions terminated due to idle_in_transaction_session_timeout or idle_session_timeout.

This parameter is disabled by default.

auto_dump.dump_on_bad_plan (boolean)

Analyze the expected and actual row counts for all queries. It uses two thresholds to identify problematic queries: auto_dump.bad_plan_count_threshold and auto_dump.bad_plan_percent_threshold. An automatic dump is triggered for a query only when the difference in row counts exceeds both thresholds simultaneously.

This parameter is disabled by default.

auto_dump.bad_plan_count_threshold (integer)

Defines a trigger condition for automatic dumps based on the absolute difference between the expected and actual row counts.

All nodes of the execution plan are analyzed. The condition is considered satisfied if the difference between the expected and actual row counts exceeds this parameter value.

If the value is set to 0, the condition is always considered satisfied. The default value is 1000000.

auto_dump.bad_plan_percent_threshold (integer)

Defines a trigger condition for automatic dumps based on the percentage difference between the expected and actual row counts. The possible value is an integer between 0 and 100 (default).

All nodes of the execution plan are analyzed. For each node, the percentage difference between expected and actual row counts is checked. The condition is considered satisfied if this difference exceeds this parameter value.

If this value is set to 0, the condition is always considered satisfied.

auto_dump.dump_on_time (boolean)

Save a dump for a query if its execution time exceeds the auto_dump.timeout value. This parameter is disabled by default.

auto_dump.timeout (integer)

Specifies the timeout value for auto_dump.dump_on_time in milliseconds. Possible values are integers greater than or equal to 0 (default). If the value is set to 0, every query is dumped.

If multiple trigger condition control parameters are specified, they are processed in the following order:

auto_dump.dump_on_cancel
auto_dump.dump_on_query_string
auto_dump.dump_on_bad_plan
auto_dump.dump_on_time

F.6.2.3. Dump Content Control Parameters

The following configuration parameters control the scope and content of automatic dumps.

auto_dump.dump_temporary_tables (boolean)

Write session temporary tables used by the current query to the dump. This parameter is disabled by default.

auto_dump.dump_persistent_tables (boolean)

Write all persistent tables used by the current query to the dump. This parameter is disabled by default.

auto_dump.dump_all_temp_tables (boolean)

Write all session temporary tables, including those used by the current query, to the dump. This parameter is disabled by default.

auto_dump.dump_data (boolean)

Write the table content to the dump. When disabled, the SQL query only includes table creation commands without populating them with data. This parameter is disabled by default.

Enable this parameter together with auto_dump.dump_temporary_tables or auto_dump.dump_persistent_tables to create an SQL file with table contents.

auto_dump.dump_indexes (boolean)

Write index creation commands for tables to the dump. This parameter is disabled by default.

auto_dump.dump_copy_data (boolean)

Specifies the method for dumping table data.

If enabled, dumps table data using the COPY TO command. As a result, a separate TXT file for each table is created, which is referenced by a COPY ... FROM statement in the dump file.

If disabled, dumps table data as INSERT statements in the dump file containing all table values.

This parameter is disabled by default.

auto_dump.dump_query (boolean)

Write the SQL query for which the dump is created to the dump. This parameter is disabled by default.

auto_dump.dump_create (boolean)

Write SQL commands for creating the tables being dumped to the dump. This parameter is disabled by default.

auto_dump.dump_plan (boolean)

Write the execution plan of the current SQL query to the dump. This parameter is disabled by default.

F.6.3. Limitations and Considerations

Use auto_dump with caution. This extension is designed as a debugging tool and cannot be used for continuous monitoring. Thus, it is not recommended to configure auto_dump to dump every query.

auto_dump operation can cause conflicts, particularly when dumping temporary tables or data. Consider the following possible issues:

The auto_dump extension is incompatible with the PREPARE TRANSACTION command when working with temporary tables. A check for operations on temporary objects occurs earlier than the check for enabled prepared transactions, so an error occurs even if max_prepared_transactions is correctly configured.
When auto_dump.dump_all_temp_tables is enabled, auto_dump cannot access temporary namespaces from autonomous transactions. A corresponding error message is raised in this case.
The performance statistics can also be affected. When auto_dump.dump_data is enabled, the extension reads table data to generate dumps and thus artificially inflates the number of sequential scans, which leads to inaccurate statistics.

Prev	Up	Next
F.5. auth_delay	Home	F.7. auto_explain