auto_explain. Автопротоколирование планов выполнения медленных операторов

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

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

Схема размещения: не используется.

Модуль auto_explain предоставляет возможность автоматического протоколирования планов выполнения медленных операторов, что позволяет обойтись без выполнения EXPLAIN вручную. Возможно применение для выявления неоптимизированных запросов в больших приложениях.

Протокол выводится в текущий журнал работы СУБД. Журналы расположены в каталоге, который указан в параметре СУБД log_directory.

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

Все параметры могут изменять только суперпользователи.

Параметр	Тип значения	Значение по умолчанию	Описание
`auto_explain.log_min_duration`	`integer`	`-1` – отключен	Время выполнения оператора в миллисекундах; при превышении указанного времени план оператора будет протоколироваться; `0` – протоколируются все планы; `-1` – протоколирование планов отключается
`auto_explain.log_analyze`	`boolean`	`false` – отключен	При включении параметра в протокол будет записываться вывод команды `EXPLAIN ANALYZE` (не просто `EXPLAIN`); замер времени на уровне узлов плана производится для всех операторов, даже если они выполняются недостаточно долго для протоколирования. Это может оказать негативное влияние на производительность; отключение `auto_explain.log_timing` исключает это влияние, при этом собирается меньше информации
`auto_explain.log_buffers`	`boolean`	`false` – отключен	Определяет вывод статистики об использовании буферов при протоколировании плана; параметр равнозначен указанию `BUFFERS` команды `EXPLAIN` и действует при включенном параметре `auto_explain.log_analyze`
`auto_explain.log_wal`	`boolean`	`false` – отключен	Определяет вывод статистики об использовании WAL при протоколировании плана; параметр равнозначен указанию `WAL` команды `EXPLAIN` и действует только при включенном параметре `auto_explain.log_analyze`
`auto_explain.log_timing`	`boolean`	`false` – отключен	Определяет вывод длительности на уровне узлов при протоколировании плана; параметр равнозначен указанию `TIMING` команды `EXPLAIN` и действует при включенном параметре `auto_explain.log_analyze`
`auto_explain.log_triggers`	`boolean`	`false` – отключен	Определяет запись в протокол статистики выполнения триггеров и действует при включенном параметре `auto_explain.log_analyze`
`auto_explain.log_verbose`	`boolean`	`false` – отключен	Определяет вывод подробных сведений при протоколировании плана; параметр равнозначен указанию `VERBOSE` команды `EXPLAIN`
`auto_explain.log_settings`	`boolean`	`false` – отключен	Определяет вывод измененных параметров конфигурации вместе с планами выполнения
`auto_explain.log_format`	`enum`	`text`	Формат вывода для `EXPLAIN`; возможные значения: – `text` (по умолчанию); – `xml`; – `json`; – `yaml`
`auto_explain.log_level`	`enum`	`LOG`	Уровень, с которым `auto_explain` будет выводить в протокол планы запросов; возможные значения: – `DEBUG5`; – `DEBUG4`; – `DEBUG3`; – `DEBUG2`; – `DEBUG1`; – `INFO`; – `NOTICE`; – `WARNING`; – `LOG` (по умолчанию)
`auto_explain.log_nested_statements`	`boolean`	`false` – отключен	Протоколирование вложенных операторов, выполняемых внутри функции; если параметр отключен, протоколируются планы запросов только верхнего уровня
`auto_explain.sample_rate`	`real`	`1` – отслеживаются все запросы	Процент операторов, которые будут отслеживаться в каждом сеансе; вложенные операторы отслеживаются совместно: – все; – никакой из них

Доработка

Доработка не проводилась.

Ограничения

Ограничения отсутствуют.

Установка

Модуль auto_explain не предоставляет функций, доступных из SQL.

Для включения необходимо загрузить его в процесс сервера. Это можно сделать в отдельном сеансе с правами суперпользователя:

LOAD 'auto_explain';

Существует следующие варианты установки параметров:

значения параметров задаются в конфигурационном файле СУБД postgresql.conf, суперпользователь может изменять значения в рамках текущего сеанса:
```
session_preload_libraries = 'auto_explain'
auto_explain.log_min_duration = '3s'
```
модуль загружается в некоторые или во все сеансы в результате включения auto_explain в переменную session_preload_libraries или в shared_preload_libraries в файле postgresql.conf. Загрузив модуль таким способом, можно отслеживать медленные запросы вне зависимости от того, когда они происходят.

Настройка

Настройка параметров выполняется в конфигурационном файле СУБД $PGDATA/postgresql.conf.

Пример:

auto_explain.log_min_duration = '3s'

Использование модуля

Включите модуль и настройте параметры в рамках текущей сессии:

LOAD 'auto_explain';
SET auto_explain.log_min_duration = 0;
SET auto_explain.log_analyze = true;

Выполните тестовый запрос:

SELECT count(*)
    FROM pg_class, pg_index
    WHERE oid = indrelid AND indisunique;

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

 count
-------
   268
(1 row)

В журнал СУБД будет выведен результат работы модуля.

Пример:

2023-03-29 13:25:14 MSK [1457]: [4-1] app=psql,user=postgres,db=postgres,client=<IP-address>,type=client backend LOG:  duration: 0.550 ms planning: 2.539 ms plan:
        Query Text: SELECT count(*)
            FROM pg_class, pg_index
            WHERE oid = indrelid AND indisunique;
        Aggregate  (cost=54.98..54.99 rows=1 width=8) (actual time=0.533..0.539 rows=1 loops=1)
          ->  Hash Join  (cost=43.64..54.31 rows=268 width=0) (actual time=0.386..0.515 rows=268 loops=1)
                Hash Cond: (pg_index.indrelid = pg_class.oid)
                ->  Seq Scan on pg_index  (cost=0.00..9.97 rows=268 width=4) (actual time=0.015..0.095 rows=268 loops=1)
                      Filter: indisunique
                      Rows Removed by Filter: 29
                ->  Hash  (cost=34.95..34.95 rows=695 width=4) (actual time=0.334..0.334 rows=695 loops=1)
                      Buckets: 1024  Batches: 1  Memory Usage: 33kB
                      ->  Seq Scan on pg_class  (cost=0.00..34.95 rows=695 width=4) (actual time=0.010..0.206 rows=695 loops=1)

Ссылки на документацию разработчика

Дополнительно поставляемый модуль auto_explain: https://www.postgresql.org/docs/current/auto-explain.html

Доработка​

Ограничения​

Установка​

Настройка​

Использование модуля​

Ссылки на документацию разработчика​