G.4. pgpro_stats — сбор статистики планирования и выполнения всех обрабатываемых сервером SQL-операторов #
Расширение pgpro_stats предоставляет возможности для сбора статистики планирования и выполнения всех обрабатываемых сервером SQL-операторов. Оно основано на модуле pg_stat_statements и реализует следующую дополнительную функциональность:
Сохранение помимо текста запросов соответствующих планов запросов.
Возможность изменения частоты сбора статистики для оптимизации связанных с ним издержек.
Вычисление статистики по событиям ожидания для выполняемых запросов.
Подсчёт статистики использования ресурсов при планировании и выполнении операторов.
Подсчёт статистики аннулирования кеша.
Вычисление дополнительной статистики архиватора.
Предоставление возможности просмотра статистики по очистке баз данных, таблиц и индексов, собранных ядром системы.
Трассировка сеансов приложений.
Создание представлений, эмулирующих другие расширения.
Примечание
Во время остановки сервера расширение pgpro_stats выгружает собранную статистику в два файла на диске в формате, который зависит от количества и порядка столбцов в представлениях pgpro_stats_statements и pgpro_stats_totals. Если этот формат изменился в новой версии pgpro_stats, то ранее сохранённые статистики не будут прочитаны при первом перезапуске сервера после обновления расширения, и в журнал будет записана ошибка:
LOG: pgpro_stats: could not load statements data file of obsolete format "pg_stat/pgpro_stats.stat"
или
LOG: pgpro_stats: could not load statements data file of obsolete format "pg_stat/pgpro_stats_totals.stat"
Содержимое файлов будет проигнорировано, а соответствующие статистики — обнулены. Чтобы узнать, изменился ли формат, ознакомьтесь с Замечаниями к выпускам для устанавливаемой версии pgpro_stats. Чтобы сохранить ранее собранные статистики, выгрузите их в CSV-файлы перед обновлением.
Описание типов и представлений, отображающих статистику аннулирования кешей, а также общая информация об этой статистике приводится в разделе Подраздел G.4.9.
G.4.1. Ограничения #
При некоторых обстоятельствах
pgpro_statsможет не сопоставить параметры в тексте запроса с теми же параметрами в соответствующем плане запроса.Некоторые запросы SPI в статистике не учитываются.
Тексты и планы некоторых запросов SPI не нормализованы.
Расширение
pgpro_statsнесовместимо с pg_stat_statements, а также другими расширениями, встраивающими свои обработчики в анализатор, планировщик или исполнитель и влияющими на разбор, планирование или выполнение запросов. Более того, если иpgpro_stats, и pg_stat_statements включены в списокshared_preload_libraries, сервер баз данных не стартует. Также обратите внимание, что для получения окончательной версии запросов и планов библиотекаpgpro_statsдолжна указываться последней в спискеshared_preload_libraries, но есть расширения, которые работают, только если их библиотека указана последней.pgpro_statsможет не работать корректно со сторонними расширениями, добавляющими в планы узлыCustomScanиForeignScan.
G.4.2. Установка и подготовка #
Расширение pgpro_stats поставляется вместе с Postgres Pro Standard в виде отдельного пакета pgpro-stats-std-18 (подробные инструкции по установке представлены в Главе 16). Установив pgpro_stats, выполните следующие действия, чтобы подготовить pgpro_stats к работе:
Добавьте
pgpro_statsв параметр shared_preload_libraries в файлеpostgresql.conf:shared_preload_libraries = 'pgpro_stats'
Перезапустите Postgres Pro Standard, чтобы изменения вступили в силу.
Когда сервер перезапустится,
pgpro_statsначнёт собирать статистику по всем базам данных в кластере. При необходимости вы можете изменять область сбора или отключить его, воспользовавшись параметрами конфигурацииpgpro_stats.Обращаться к собираемой статистике вы сможете после того, как создадите расширение
pgpro_stats:CREATE EXTENSION pgpro_stats;
Кроме того, необходимо включить вычисление идентификатора запроса, чтобы расширение pgpro_stats было активно. Это происходит автоматически, если для compute_query_id задано значение auto или on, или загружен любой сторонний модуль, вычисляющий идентификаторы запросов.
G.4.3. Использование #
G.4.3.1. Сбор статистики по операторам запросов и планам #
После того как расширение pgpro_stats будет установлено, оно начнёт собирать статистику по выполняемым операторам. Собираемые данные во многом пересекаются с теми, что собирает pg_stat_statements, но также включают информацию о планах запросов и событиях ожидания для каждого типа запроса. Полученная статистика сохраняется в кольцевом буфере в памяти, а прочитать её можно через представление pgpro_stats_statements.
По умолчанию pgpro_stats собирает статистику по всем операторам, с учётом значений параметров pgpro_stats.track и pgpro_stats.track_utility. Однако в целях оптимизации производительности вы можете уменьшить частоту выборки, воспользовавшись параметром pgpro_stats.query_sample_rate, и тогда pgpro_stats для вычисления статистики будет случайным образом выбирать заданную долю запросов из общего количества.
Для сбора статистики по событиям ожидания pgpro_stats производит выборки с определённой периодичностью. Эта периодичность задаётся параметром pgpro_stats.profile_period и по умолчанию равна 10 мс. Если выборка показывает, что процесс находится в состоянии ожидания, к общей длительности ожидания события добавляется значение pgpro_stats.profile_period. Таким образом, оценка длительности ожидания остаётся корректной даже при изменениях значения pgpro_stats.profile_period. Если вас не интересует статистика по событиям ожидания, сбор этой информации можно отключить, установив для параметра pgpro_stats.enable_profile значение false.
Показатели pgpro_stats_statements.plans и pgpro_stats_statements.calls не обязательно должны совпадать, так как статистика планирования и выполнения обновляется в конце соответствующей фазы и только при успешном завершении этой фазы. Например, если для оператора успешно выполнилось планирование, но во время выполнения произошла ошибка, изменится только статистика планирования. Если же планирование пропускается по причине использования кешированного плана, увеличивается только счётчик выполнения.
Например, давайте создадим таблицу со случайными данными и построим в ней индекс:
CREATE TABLE test AS (SELECT i, random() x FROM generate_series(1,1000000) i); CREATE INDEX test_x_idx ON test (x);
Выполните несколько раз следующий запрос с различными значениями :x_min и :x_max:
select * from test where x >= :x_min and x <= :x_max;
После этого собранная статистика должна появиться в представлении pgpro_stats_statements:
SELECT queryid, query, planid, plan, wait_stats FROM pgpro_stats_statements WHERE query LIKE 'select * from test where%';
-[ RECORD 1 ]----------------------------------------------------------------------------------------------------------
queryid | 1109491335754870054
query | select * from test where x >= $1 and x <= $2
planid | 8287793242828473388
plan | Gather
| Output: i, x
| Workers Planned: 2
| -> Parallel Seq Scan on public.test
| Output: i, x
| Filter: ((test.x >= $3) AND (test.x <= $4))
|
wait_stats | {"IO": {"DataFileRead": 10}, "IPC": {"BgWorkerShutdown": 10}, "Total": {"IO": 10, "IPC": 10, "Total": 20}}
-[ RECORD 2 ]----------------------------------------------------------------------------------------------------------
queryid | 1109491335754870054
query | select * from test where x >= $1 and x <= $2
planid | -9045072158333552619
plan | Bitmap Heap Scan on public.test
| Output: i, x
| Recheck Cond: ((test.x >= $3) AND (test.x <= $4))
| -> Bitmap Index Scan on test_x_idx
| Index Cond: ((test.x >= $5) AND (test.x <= $6))
|
wait_stats | {"IO": {"DataFileRead": 40}, "Total": {"IO": 40, "Total": 40}}
-[ RECORD 3 ]----------------------------------------------------------------------------------------------------------
queryid | 1109491335754870054
query | select * from test where x >= $1 and x <= $2
planid | -1062789671372193287
plan | Seq Scan on public.test
| Output: i, x
| Filter: ((test.x >= $3) AND (test.x <= $4))
|
wait_stats | NULL
-[ RECORD 4 ]----------------------------------------------------------------------------------------------------------
queryid | 1109491335754870054
query | select * from test where x >= $1 and x <= $2
planid | -1748292253893834280
plan | Index Scan using test_x_idx on public.test
| Output: i, x
| Index Cond: ((test.x >= $3) AND (test.x <= $4))
|
wait_stats | NULLG.4.3.2. Сбор дополнительных метрик #
Используя pgpro_stats, вы можете определить дополнительные интересующие вас метрики. Собираемые данные будут накапливаться в кольцевом буфере для последующей передачи их в систему мониторинга. Этот подход лучше, чем непосредственный опрос базы данных системой мониторинга, так как в случае кратковременного прерывания соединения собранные данные не будут потеряны, а сохранятся в буфере и могут быть считаны позднее.
Чтобы настроить сбор дополнительной метрики, выполните следующее:
Для каждой метрики необходимо определить все параметры конфигурации, перечисленные в Подразделе G.4.7.2. В именах параметров должен присутствовать уникальный идентификатор (номер) метрики.
Например, чтобы раз в 60 секунд собирать информацию о раздувании индексов, вы можете определить первую дополнительную метрику, установив соответствующие параметры следующим образом:
pgpro_stats.metric_1_name = index_bloat pgpro_stats.metric_1_query = 'select iname, ibloat, ipages from bloat' pgpro_stats.metric_1_db = 'postgres' pgpro_stats.metric_1_user = postgres pgpro_stats.metric_1_period = '60s'
Перезапустите сервер.
pgpro_statsначинает собирать статистику по выполняемым операторам и сохраняет её в кольцевом буфере; собранная статистика появляется в представленииpgpro_stats_metrics:SELECT * FROM pgpro_stats_metrics;
При необходимости настройте экспорт данных в систему мониторинга, которую вы используете.
G.4.4. Представления #
G.4.4.1. Представление pgpro_stats_statements #
Статистика, собираемая модулем, выдаётся через представление с именем pgpro_stats_statements. Это представление содержит отдельные строки для каждой комбинации идентификатора базы данных, идентификатора пользователя, идентификатора запроса и идентификатора плана (но в количестве, не превышающем максимальное число различных операторов, которые может отслеживать модуль). Столбцы представления показаны в Таблице G.75.
Таблица G.75. Столбцы pgpro_stats_statements
| Имя | Тип | Ссылки | Описание |
|---|---|---|---|
userid | oid | | OID пользователя, выполнявшего оператор |
dbid | oid | | OID базы данных, в которой выполнялся оператор |
toplevel | bool | True, если данный запрос выполнялся на верхнем уровне (всегда true, если для параметра pgpro_stats.track задано значение top) | |
queryid | bigint | Хеш-код для идентификации нормализованного запроса | |
planid | bigint | Хеш-код для идентификации нормализованного плана оператора | |
query | text | Текст, представляющий оператор | |
plan | text | План запроса, представленный в формате, определённом параметром конфигурации pgpro_stats.plan_format | |
plans | int8 | Число операций планирования этого оператора (если включён параметр pgpro_stats.track_planning, иначе 0) | |
total_plan_time | float8 | Общее время, затраченное на планирование этого оператора в миллисекундах (если включён параметр pgpro_stats.track_planning, иначе 0) | |
min_plan_time | float8 | Минимальное время, затраченное на планирование этого оператора в миллисекундах (если включён параметр pgpro_stats.track_planning, иначе 0) | |
max_plan_time | float8 | Максимальное время, затраченное на планирование этого оператора в миллисекундах (если включён параметр pgpro_stats.track_planning, иначе 0) | |
mean_plan_time | float8 | Среднее время, затраченное на планирование этого оператора в миллисекундах (если включён параметр pgpro_stats.track_planning, иначе 0) | |
stddev_plan_time | float8 | Стандартное отклонение времени, затраченного на планирование этого оператора в миллисекундах (если включён параметр pgpro_stats.track_planning, иначе 0) | |
plan_rusage | pgpro_stats_rusage | Статистика использования ресурсов при планировании оператора. | |
calls | int8 | Счётчик выполнений данного оператора | |
total_exec_time | float8 | Общее время, затраченное на выполнение оператора, в миллисекундах | |
min_exec_time | float8 | Минимальное время, потраченное на выполнение оператора, в миллисекундах | |
max_exec_time | float8 | Максимальное время, потраченное на выполнение оператора, в миллисекундах | |
mean_exec_time | float8 | Среднее время, потраченное на выполнение оператора, в миллисекундах | |
stddev_exec_time | float8 | Стандартное отклонение времени, затраченного на выполнение оператора, в миллисекундах | |
exec_rusage | pgpro_stats_rusage | Статистика использования ресурсов при выполнении оператора. | |
rows | int8 | Общее число строк, полученных или затронутых оператором | |
shared_blks_hit | int8 | Общее число попаданий разделяемых блоков в кеш для данного оператора | |
shared_blks_read | int8 | Общее число разделяемых блоков, прочитанных данным оператором | |
shared_blks_dirtied | int8 | Общее число разделяемых блоков, «загрязнённых» данным оператором | |
shared_blks_written | int8 | Общее число разделяемых блоков, записанных данным оператором | |
local_blks_hit | int8 | Общее число попаданий локальных блоков в кеш для данного оператора | |
local_blks_read | int8 | Общее число локальных блоков, прочитанных данным оператором | |
local_blks_dirtied | int8 | Общее число локальных блоков, «загрязнённых» данным оператором | |
local_blks_written | int8 | Общее число локальных блоков, записанных данным оператором | |
temp_blks_read | int8 | Общее число временных блоков, прочитанных данным оператором | |
temp_blks_written | int8 | Общее число временных блоков, записанных данным оператором | |
shared_blk_read_time | float8 | Общее время, затраченное оператором на чтение разделяемых блоков, в миллисекундах (если включён track_io_timing, иначе ноль) | |
shared_blk_write_time | float8 | Общее время, затраченное оператором на запись разделяемых блоков, в миллисекундах (если включён track_io_timing, иначе ноль) | |
local_blk_read_time | float8 | Общее время, затраченное оператором на чтение локальных блоков, в миллисекундах (если включён track_io_timing, или ноль в противном случае). В версиях Postgres Pro ниже 17 всегда содержит ноль. | |
local_blk_write_time | float8 | Общее время, затраченное оператором на запись локальных блоков, в миллисекундах (если включён track_io_timing, или ноль в противном случае). В версиях Postgres Pro ниже 17 всегда содержит ноль. | |
temp_blk_read_time | float8 | Общее время, затраченное оператором на чтение временных блоков, в миллисекундах (если включён track_io_timing, или ноль в противном случае). В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
temp_blk_write_time | float8 | Общее время, затраченное оператором на запись временных блоков, в миллисекундах (если включён track_io_timing, или ноль в противном случае). В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
wal_records | int8 | Общее число записей WAL, сгенерированных при выполнении оператора | |
wal_fpi | int8 | Общее число образов полных страниц в WAL, сгенерированных при выполнении оператора | |
wal_bytes | numeric | Общий объём WAL (в байтах), сгенерированный при выполнении оператора | |
wal_buffers_full | bigint | Количество случаев переполнения буферов WAL. В версиях Postgres Pro ниже 18 всегда содержит ноль. | |
jit_functions | int8 | Общее число функций, скомпилированных в JIT-код при выполнении оператора. В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
jit_generation_time | float8 | Общее время, затраченное на компиляцию JIT-кода при выполнении оператора, в миллисекундах. В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
jit_inlining_count | int8 | Количество встраиваний функций, используемых в операторе. В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
jit_inlining_time | float8 | Общее время, затраченное на встраивание функций при выполнении оператора, в миллисекундах. В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
jit_optimization_count | int8 | Количество JIT-оптимизаций для оператора. В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
jit_optimization_time | float8 | Общее время, затраченное на JIT-оптимизацию при выполнении оператора, в миллисекундах. В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
jit_emission_count | int8 | Сколько раз выдавался код при выполнении оператора. В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
jit_emission_time | float8 | Общее время, затраченное на выдачу кода при выполнении оператора, в миллисекундах. В версиях Postgres Pro ниже 15 всегда содержит ноль. | |
jit_deform_count | int8 | Общее число функций преобразования кортежей, скомпилированных в JIT-код при выполнении оператора. В версиях Postgres Pro ниже 17 всегда содержит ноль. | |
jit_deform_time | float8 | Общее время, затраченное оператором на компилирование функций преобразования кортежей в JIT-код, в миллисекундах. В версиях Postgres Pro ниже 17 всегда содержит ноль. | |
parallel_workers_to_launch | bigint | Число параллельных рабочих процессов, которые планируется запустить. В версиях Postgres Pro ниже 18 всегда содержит ноль. | |
parallel_workers_launched | bigint | Число запущенных параллельных рабочих процессов. В версиях Postgres Pro ниже 18 всегда содержит ноль. | |
wait_stats | jsonb | Объект типа jsonb, содержащий статистику по событиям ожидания для каждого выполнения запроса по соответствующему плану. Все показатели представлены в миллисекундах и кратны параметру конфигурации pgpro_stats.profile_period. | |
inval_msgs | pgpro_stats_inval_msgs | Число сообщений аннулирования кеша по типам, выданных при выполнении оператора (если это поддерживает сервер, иначе — 0). | |
stats_since | timestamp with time zone | Время начала сбора статистики по этому оператору | |
minmax_stats_since | timestamp with time zone | Время начала сбора статистики минимальных/максимальных значений по этому оператору (столбцы min_plan_time, max_plan_time, min_exec_time и max_exec_time) |
Аналогично расширению pg_stat_statements, DML запросы (то есть SELECT, INSERT, UPDATE, DELETE и MERGE) в pgpro_stats объединяются в одну запись, когда они имеют идентичные структуры запросов согласно внутреннему вычисленному хешу. Обычно два запроса будут считаться равными при таком сравнении, если они семантически равнозначны, не считая значений констант, фигурирующих в запросе. Когда значение константы игнорируется в целях сравнения запроса с другими запросами, эта константа заменяется в выводе pgpro_stats обозначением параметра, например, $k, где k - натуральное число. Если в запросе уже есть параметры, то начальное значение k равно номеру, следующим за номером последнего параметра $n в исходном тексте запроса. Если параметров нет, то начальное значение k равно единице. Стоит отметить, что в некоторых случаях на эту нумерацию могут влиять скрытые символы параметров. Например, PL/pgSQL применяет такие символы для добавления в запросы значений локальных переменных функций, так что оператор PL/pgSQL вида SELECT i + 1 INTO j будет представлен в тексте как SELECT i + $2.
В некоторых случаях запросы с визуально различными текстами могут быть объединены в одну запись pgpro_stats_statements; как описано выше, это характерно для семантически равнозначных запросов. Кроме того, если единственное различие между запросами — число элементов в списке констант, список сжимается до одного элемента, но отображается с закомментированным индикатором списка:
=# SELECT pgpro_stats_statements_reset(); =# SELECT * FROM test WHERE a IN (1, 2, 3, 4, 5, 6, 7); =# SELECT * FROM test WHERE a IN (1, 2, 3, 4, 5, 6, 7, 8); =# SELECT query, calls FROM pgpro_stats_statements WHERE query LIKE 'SELECT%'; -[ RECORD 1 ]------------------------------ query | SELECT * FROM test WHERE a IN ($1 /*, ... */) calls | 2
Кроме этих случаев есть небольшая вероятность, что из-за наложений хеша несвязанные запросы могут оказаться объединёнными в одной записи. (Однако это невозможно для запросов, относящимся к разным пользователям или базам данных.)
Подобный механизм объединения текстов pgpro_stats использует и для текстов планов. При этом делается попытка сопоставить номера констант в тексте плана соответствующим номерам констант в тексте запроса. Если такая попытка для какой-либо константы в тексте плана оканчивается неудачей, то ей присваивается следующий номер, больший максимального номера заменённой константы в тексте запроса. Например, для запроса:
SELECT 1::int, 'abc'::VARCHAR(3), 2::int;
в его тексте и в тексте соответствующего плана pgpro_stats подставит номера констант следующим образом:
postgres=# SELECT query, plan FROM pgpro_stats_statements;
query | plan
------------------------------------------------+--------------------------------------------------
SELECT $1::int, $2::VARCHAR(3), $3::int | Result +
| Output: $1, $4, $3 +В данном тексте плана удалось сопоставить константы с номерами 1 и 3 из текста запроса, а константу с номером 2 сопоставить не удалось, и она была заменена номером, следующим за максимальным номером в тексте запроса — номером 4.
При подстановке номеров в тексте плана делается исключение для номера версии XML документа. Если в исходном запросе он был задан константой, например '1.0', то в тексте плана это значение сохранится как есть и не будет заменено на подстановочный символ вида $k. Если в исходном запросе номер версии XML документа был задан выражением, то подстановка символов вместо констант будет сделана по обычным правилам.
В pgpro_stats запросы, имеющие один и тот же хеш текста и один и тот же хеш плана, объединяются в одну строку pgpro_stats_statements. После замены констант в тексте плана в остальном план будет соответствовать тексту плана первого из объединённых запросов, попавших в статистику. Однако тексты других планов с тем же хешем могут отличаться не только заменёнными константами. Рассмотрим следующий пример.
Пример G.1. План, выполненный с отсечением секций
Рассмотрим подготовленный запрос:
PREPARE test_stmt(bigint, bigint, bigint) AS SELECT * FROM ptest WHERE category_id IN ($1,$2,$3);
Он обращается к таблице ptest, секционированной по столбцу category_id.
Чтобы в дальнейшем выбирался общий план, установим следующее значение параметра конфигурации:
SET plan_cache_mode TO force_generic_plan;
И пусть этот запрос выполняется с разными значениями:
EXECUTE test_stmt(1,2,3); EXECUTE test_stmt(2,3,4);
В pgpro_stats эти запросы будут объединены, и будет выведен следующий текст плана:
Append
Subplans Removed: 17
-> Seq Scan on public.ptest_1
Output: ptest_1.id, ptest_1.category_id
Filter: (ptest_1.category_id = ANY (ARRAY[$1, $2, $3]))
-> Seq Scan on public.ptest_2
Output: ptest_2.id, ptest_2.category_id
Filter: (ptest_2.category_id = ANY (ARRAY[$1, $2, $3]))
-> Seq Scan on public.ptest_3
Output: ptest_3.id, ptest_3.category_id
Filter: (ptest_3.category_id = ANY (ARRAY[$1, $2, $3])) Константы в ANY (ARRAY[$1, $2, $3]) были заменены, но имена таблиц секций ptest_1, ptest_2, ptest_3 соответствуют первому сохранённому плану, хотя план второго запроса включал сканирование других секций (ptest_2, ptest_3, ptest_4). Эти планы считаются эквивалентными, так как хеш плана вычислен на основе исходного общего плана, который включает подпланы со сканированием всех секций. Но pgpro_stats сохраняет только текст реально выполненного плана, с отсечением секций во время выполнения. Поэтому текст плана включает только просканированные секции (в первом сохранённом запросе). Subplans Removed: 17 показывает, что сканирование остальных секций было удалено при отсечении секций.
G.4.4.2. Представление pgpro_stats_totals #
Агрегированная статистика, собранная модулем, выдаётся через представление pgpro_stats_totals. Это представление содержит отдельные строки для каждого отдельного объекта БД (но в количестве, не превышающем максимальное число различных объектов, которое может отслеживать модуль). Столбцы представления показаны в Таблице G.76.
Таблица G.76. Столбцы pgpro_stats_totals
| Имя | Тип | Описание |
|---|---|---|
object_type | text | Тип объекта, для которого агрегируется статистика: «cluster» (кластер БД), «database» (база данных), «user» (пользователь), «client_addr» (адрес клиента), «application» (приложение), «backend» (обслуживающий процесс), «session» (сеанс) |
object_id | bigint | Идентификатор объекта: OID для баз и пользователей, PID для обслуживающих процессов, NULL для иных объектов |
object_name | text | Текстовое имя объекта либо NULL |
queries_planned | int8 | Число спланированных запросов |
total_plan_time | float8 | Общее время, затраченное на планирование операторов, в миллисекундах |
total_plan_rusage | pgpro_stats_rusage | Агрегированная статистика использования ресурсов при планировании операторов |
queries_executed | int8 | Число выполненных запросов |
total_exec_time | float8 | Общее время, затраченное на выполнение операторов, в миллисекундах |
total_exec_rusage | pgpro_stats_rusage | Агрегированная статистика использования ресурсов при выполнении операторов |
rows | int8 | Общее число строк, полученных или затронутых операторами |
shared_blks_hit | int8 | Общее число попаданий разделяемых блоков в кеш для данных операторов |
shared_blks_read | int8 | Общее число разделяемых блоков, прочитанных операторами |
shared_blks_dirtied | int8 | Общее число разделяемых блоков, «загрязнённых» операторами |
shared_blks_written | int8 | Общее число разделяемых блоков, записанных операторами |
local_blks_hit | int8 | Общее число попаданий локальных блоков в кеш для данных операторов |
local_blks_read | int8 | Общее число локальных блоков, прочитанных операторами |
local_blks_dirtied | int8 | Общее число локальных блоков, «загрязнённых» операторами |
local_blks_written | int8 | Общее число локальных блоков, записанных операторами |
temp_blks_read | int8 | Общее число локальных блоков, прочитанных операторами |
temp_blks_written | int8 | Общее число временных блоков, записанных операторами |
shared_blk_read_time | float8 | Общее время, затраченное операторами на чтение разделяемых блоков, в миллисекундах (если включён track_io_timing, иначе ноль) |
shared_blk_write_time | float8 | Общее время, затраченное операторами на запись разделяемых блоков, в миллисекундах (если включён track_io_timing, иначе ноль) |
local_blk_read_time | float8 | Общее время, затраченное операторами на чтение локальных блоков, в миллисекундах (если включён track_io_timing, или ноль в противном случае). В версиях Postgres Pro ниже 17 всегда содержит ноль. |
local_blk_write_time | float8 | Общее время, затраченное операторами на запись локальных блоков, в миллисекундах (если включён track_io_timing, или ноль в противном случае). В версиях Postgres Pro ниже 17 всегда содержит ноль. |
temp_blk_read_time | float8 | Общее время, затраченное операторами на чтение временных блоков, в миллисекундах (если включён track_io_timing, или ноль в противном случае). В версиях Postgres Pro ниже 15 всегда содержит ноль. |
temp_blk_write_time | float8 | Общее время, затраченное операторами на запись временных блоков, в миллисекундах (если включён track_io_timing, или ноль в противном случае). В версиях Postgres Pro ниже 15 всегда содержит ноль. |
wal_records | int8 | Общее число записей WAL, сгенерированных при выполнении операторов |
wal_fpi | int8 | Общее число образов полных страниц в WAL, сгенерированных при выполнении операторов |
wal_bytes | numeric | Общий объём WAL (в байтах), сгенерированный при выполнении операторов |
wal_buffers_full | bigint | Общее количество случаев переполнения буферов WAL. В версиях Postgres Pro ниже 18 всегда содержит ноль. |
jit_functions | int8 | Общее число функций, скомпилированных в JIT-код при выполнении операторов. В версиях Postgres Pro ниже 15 всегда содержит ноль. |
jit_generation_time | float8 | Общее время, затраченное на компиляцию JIT-кода при выполнении операторов, в миллисекундах. В версиях Postgres Pro ниже 15 всегда содержит ноль. |
jit_inlining_count | int8 | Количество встраиваний функций, используемых в операторах. В версиях Postgres Pro ниже 15 всегда содержит ноль. |
jit_inlining_time | float8 | Общее время, затраченное на встраивание функций при выполнении операторов, в миллисекундах. В версиях Postgres Pro ниже 15 всегда содержит ноль. |
jit_optimization_count | int8 | Количество JIT-оптимизаций для операторов. В версиях Postgres Pro ниже 15 всегда содержит ноль. |
jit_optimization_time | float8 | Общее время, затраченное на JIT-оптимизацию при выполнении операторов, в миллисекундах. В версиях Postgres Pro ниже 15 всегда содержит ноль. |
jit_emission_count | int8 | Сколько раз выдавался код при выполнении операторов. В версиях Postgres Pro ниже 15 всегда содержит ноль. |
jit_emission_time | float8 | Общее время, затраченное на выдачу кода при выполнении операторов, в миллисекундах. В версиях Postgres Pro ниже 15 всегда содержит ноль. |
jit_deform_count | int8 | Общее число функций преобразования кортежей, скомпилированных в JIT-код при выполнении операторов. В версиях Postgres Pro ниже 17 всегда содержит ноль. |
jit_deform_time | float8 | Общее время, затраченное операторами на компилирование функций преобразования кортежей в JIT-код, в миллисекундах. В версиях Postgres Pro ниже 17 всегда содержит ноль. |
parallel_workers_to_launch | bigint | Число параллельных рабочих процессов, которые операторы планируют запустить. В версиях Postgres Pro ниже 18 всегда содержит ноль. |
parallel_workers_launched | bigint | Число параллельных рабочих процессов, запущенных операторами. В версиях Postgres Pro ниже 18 всегда содержит ноль. |
wait_stats | jsonb | Объект типа jsonb, содержащий статистику по событиям ожидания для каждого выполнения запроса. Все показатели представлены в миллисекундах и кратны параметру конфигурации pgpro_stats.profile_period. |
inval_msgs | pgpro_stats_inval_msgs | Число сообщений аннулирования кеша по типам, выданных при выполнении операторов (если это поддерживает сервер, иначе — 0). |
cache_resets | int4 | Число сбросов разделяемого кеша (только для кластера БД, баз данных и обслуживающих процессов). Увеличивается для обслуживающего процесса, когда он получает сообщение, вызывающее полный сброс кеша. |
stats_since | timestamp with time zone | Время, когда начался сбор статистики по операторам |
G.4.4.3. Представление pgpro_stats_info #
Статистика самого модуля pgpro_stats собирается и выдаётся через представление с именем pgpro_stats_info. Это представление содержит только одну строку. Столбцы представления показаны в Таблице G.77.
Таблица G.77. Столбцы pgpro_stats_info
| Имя | Тип | Описание |
|---|---|---|
dealloc | bigint | Сколько всего раз в pgpro_stats_statements отбрасывались записи о редко выполняемых операторах, поскольку на обработку поступало больше различных операторов, чем задано в параметре pgpro_stats.max |
stats_reset | timestamp with time zone | Время последнего сброса всех статистических данных в представлении pgpro_stats_statements |
G.4.4.4. Представление pgpro_stats_metrics #
Метрики, собранные модулем pgpro_stats, выводятся в представлении pgpro_stats_metrics. В таблице ниже описаны столбцы этого представления.
Таблица G.78. Столбцы pgpro_stats_metrics
| Имя | Тип | Описание |
|---|---|---|
metric_number | int4 | Уникальный идентификатор собираемой метрики, назначаемый пользователем. Этот идентификатор входит в имена параметров, определяющих метрику. |
metric_name | text | Имя метрики, определённое параметром pgpro_stats.metric_ |
db_name | text | Имя базы данных, для которой была получена метрика |
ts | timestamptz | Время, когда было вычислено значение метрики |
value | jsonb | Результат запроса, производившего вычисление метрики. Он сериализуется в типе jsonb как массив объектов, полученных с помощью функции to_jsonb(. В случае ошибки возвращается один объект, содержащий поля code (код ошибки), message (сообщение), detail (подробности) и hint (подсказка). |
G.4.4.5. Представление pgpro_stats_archiver #
Представление pgpro_stats_archiver будет содержать одну строку, показывающую данные о процессе архивации кластера.
Таблица G.79. Столбцы pgpro_stats_archiver
| Столбец | Тип | Описание |
|---|---|---|
archived_count | bigint | Число файлов WAL, которые были успешно заархивированы |
last_archived_wal | text | Имя последнего успешно заархивированного файла WAL |
last_archived_time | timestamp with time zone | Время последней успешной архивации |
failed_count | bigint | Число неудачных попыток архивации файлов WAL |
last_failed_wal | text | Имя файла WAL, который обрабатывался в ходе последней неудавшейся архивации |
last_failed_time | timestamp with time zone | Время последней неудавшейся архивации |
active_time | int8 | Общее время, в течение которого процесс архивации был активен |
archive_command_time | int8 | Общее время выполнения команды архивации |
stats_reset | timestamp with time zone | Последнее время сброса этих статистических данных |
G.4.4.6. Представление pgpro_stats_vacuum_database #
Важно
Начиная с Postgres Pro 16, это представление не содержит данных, поскольку отображаемые в нём статистики доступны через представление каталога pg_stats_vacuum_database (за подробностями обратитесь к разделу Системные представления).
Представление pgpro_stats_vacuum_database будет содержать по одной строке для каждой базы данных в текущем кластере, показывая статистику очистки этой конкретной БД. Эта статистика собирается ядром системы, как описано в Разделе 27.2. В таблице ниже описаны столбцы представления.
Таблица G.80. Столбцы pgpro_stats_vacuum_database
| Столбец | Тип | Описание |
|---|---|---|
dbid | oid | OID базы данных |
total_blks_read | int8 | Количество блоков базы данных, прочитанных операциями очистки для этой БД |
total_blks_hit | int8 | Количество попаданий в буферный кеш блоков базы данных в процессе операций очистки, выполненных для этой БД |
total_blks_dirtied | int8 | Количество блоков базы данных, загрязнённых операциями очистки для этой БД |
total_blks_written | int8 | Количество блоков базы данных, записанных операциями очистки для этой БД |
wal_records | int8 | Общее число записей WAL, сгенерированных операциями очистки для этой базы данных |
wal_fpi | int8 | Общее число образов полных страниц в WAL, сгенерированных операциями очистки для этой базы данных |
wal_bytes | numeric | Общий объём WAL (в байтах), сгенерированный операциями очистки для этой базы данных |
blk_read_time | float8 | Общее время, затраченное на чтение блоков базы данных операциями очистки, выполненными для этой БД, в миллисекундах (если включён параметр track_io_timing, или ноль в противном случае) |
blk_write_time | float8 | Общее время, затраченное на запись блоков базы данных операциями очистки, выполненными для этой БД, в миллисекундах (если включён параметр track_io_timing, или ноль в противном случае) |
delay_time | float8 | Время простоя в точке задержки при выполнении операций очистки для этой базы данных, в миллисекундах (за подробностями обратитесь к Подразделу 18.10.2). |
system_time | float8 | Время использования процессора в режиме ядра при очистке этой базы данных, в миллисекундах |
user_time | float8 | Время использования процессора в пользовательском режиме при очистке этой базы данных, в миллисекундах |
total_time | float8 | Общее время, затраченное на очистку этой базы данных, в миллисекундах |
interrupts | int4 | Сколько раз операции очистки для этой базы данных были прерваны из-за каких-либо ошибок |
G.4.4.7. Представление pgpro_stats_vacuum_tables #
Важно
Начиная с Postgres Pro 16, это представление не содержит данных, поскольку отображаемые в нём статистики доступны через представление каталога pg_stats_vacuum_tables (за подробностями обратитесь к разделу Системные представления).
Представление pgpro_stats_vacuum_tables будет содержать по одной строке для каждой таблицы в текущей базе данных (включая таблицы TOAST), показывая статистику очистки этой конкретной таблицы. Эта статистика собирается ядром системы, как описано в Разделе 27.2. В таблице ниже описаны столбцы представления.
Таблица G.81. Столбцы pgpro_stats_vacuum_tables
| Столбец | Тип | Описание |
|---|---|---|
relid | oid | OID таблицы |
schema | name | Имя схемы, в которой расположена эта таблица |
relname | name | Имя данной таблицы |
total_blks_read | int8 | Количество блоков БД, прочитанных операциями очистки для этой таблицы |
total_blks_hit | int8 | Количество попаданий в буферный кеш блоков базы данных в процессе операций очистки, выполненных для этой таблицы |
total_blks_dirtied | int8 | Количество блоков базы данных, загрязнённых операциями очистки для этой таблицы |
total_blks_written | int8 | Количество блоков базы данных, записанных операциями очистки для этой таблицы |
rel_blks_read | int8 | Количество блоков, прочитанных из этой таблицы операциями очистки |
rel_blks_hit | int8 | Сколько раз блоки этой таблицы уже обнаруживались в буферном кеше операциями очистки, так что чтение с диска не потребовалось (здесь учитываются только случаи обнаружения блоков в кеше Postgres Pro, а не в кеше операционной системы) |
pages_scanned | int8 | Количество страниц, к которым обращались операции очистки, выполненные для этой таблицы |
pages_removed | int8 | Количество страниц, удалённых из физического хранилища операциями очистки для этой таблицы |
pages_frozen | int8 | Сколько раз страницы этой таблицы были помечены операциями очистки в карте видимости как полностью замороженные |
pages_all_visible | int8 | Сколько раз страницы этой таблицы были помечены операциями очистки в карте видимости как полностью видимые |
tuples_deleted | int8 | Количество «мёртвых» кортежей, удалённых операциями очистки из этой таблицы |
tuples_frozen | int8 | Количество кортежей этой таблицы, помеченных операциями очистки как замороженные |
dead_tuples | int8 | Количество «мёртвых» кортежей, оставленных операциями очистки в этой таблице из-за видимости этих кортежей в транзакциях |
index_vacuum_count | int8 | Сколько раз была выполнена очистка индексов этой таблицы |
rev_all_frozen_pages | int8 | Сколько раз для страниц данной таблицы снималась метка полной заморозки в карте видимости |
rev_all_visible_pages | int8 | Сколько раз для страниц данной таблицы снималась метка полной видимости в карте видимости |
wal_records | int8 | Общее число записей WAL, сгенерированных операциями очистки для этой таблицы |
wal_fpi | int8 | Общее число образов полных страниц в WAL, сгенерированных операциями очистки для этой таблицы |
wal_bytes | numeric | Общий объём WAL (в байтах), сгенерированный операциями очистки для этой таблицы |
blk_read_time | float8 | Общее время, затраченное на чтение блоков БД операциями очистки, выполненными для этой таблицы, в миллисекундах (если включён параметр track_io_timing, или ноль в противном случае) |
blk_write_time | float8 | Общее время, затраченное на запись блоков БД операциями очистки, выполненными для этой таблицы, в миллисекундах (если включён параметр track_io_timing, или ноль в противном случае) |
delay_time | float8 | Время простоя в точке задержки при выполнении операций очистки для этой таблицы, в миллисекундах (за подробностями обратитесь к Подразделу 18.10.2). |
system_time | float8 | Время использования процессора в режиме ядра при очистке этой таблицы, в миллисекундах |
user_time | float8 | Время использования процессора в пользовательском режиме при очистке этой таблицы, в миллисекундах |
total_time | float8 | Общее время, затраченное на очистку этой таблицы, в миллисекундах |
interrupts | integer | Сколько раз операции очистки для этой таблицы были прерваны из-за каких-либо ошибок |
Столбцы total_*, wal_* и blk_* содержат данные об очистке индексов этой таблицы, а столбцы system_time и user_time содержат только данные об очистке кучи.
G.4.4.8. Представление pgpro_stats_vacuum_indexes #
Важно
Начиная с Postgres Pro 16, это представление не содержит данных, поскольку отображаемые в нём статистики доступны через представление каталога pg_stats_vacuum_indexes (за подробностями обратитесь к разделу Системные представления).
Представление pgpro_stats_vacuum_indexes будет содержать одну строку для каждого индекса в текущей базе данных (включая индексы таблицы TOAST), показывая статистику очистки этого конкретного индекса. Эта статистика собирается ядром системы, как описано в Разделе 27.2. В таблице ниже описаны столбцы представления.
Таблица G.82. Столбцы pgpro_stats_vacuum_indexes
| Столбец | Тип | Описание |
|---|---|---|
relid | oid | OID индекса |
schema | name | Имя схемы, в которой расположен этот индекс |
relname | name | Имя этого индекса |
total_blks_read | int8 | Количество блоков БД, прочитанных операциями очистки для этого индекса |
total_blks_hit | int8 | Количество попаданий в буферный кеш блоков базы данных в процессе операций очистки, выполненных для этого индекса |
total_blks_dirtied | int8 | Количество блоков базы данных, загрязнённых операциями очистки для этого индекса |
total_blks_written | int8 | Количество блоков базы данных, записанных операциями очистки для этого индекса |
rel_blks_read | int8 | Количество блоков, прочитанных для этого индекса операциями очистки |
rel_blks_hit | int8 | Сколько раз блоки этого индекса уже обнаруживались в буферном кеше операциями очистки, так что чтение с диска не потребовалось (здесь учитываются только случаи обнаружения блоков в кеше Postgres Pro, а не в кеше операционной системы ОС) |
pages_deleted | int8 | Количество страниц, которые были удалены операциями очистки, выполненными для этого индекса |
tuples_deleted | int8 | Количество «мёртвых» кортежей, удалённых операциями очистки для этого индекса |
wal_records | int8 | Общее число записей WAL, сгенерированных операциями очистки для этого индекса |
wal_fpi | int8 | Общее число образов полных страниц в WAL, сгенерированных операциями очистки для этого индекса |
wal_bytes | numeric | Общий объём WAL (в байтах), сгенерированный операциями очистки для этого индекса |
blk_read_time | float8 | Общее время, затраченное на чтение блоков БД операциями очистки, выполненными для этого индекса, в миллисекундах (если включён параметр track_io_timing, или ноль в противном случае) |
blk_write_time | float8 | Общее время, затраченное на запись блоков БД операциями очистки, выполненными для этой таблицы, в миллисекундах (если включён параметр track_io_timing, или ноль в противном случае) |
delay_time | float8 | Время простоя в точке задержки при выполнении операций очистки для этого индекса, в миллисекундах (за подробностями обратитесь к Подразделу 18.10.2). |
system_time | float8 | Время использования процессора в режиме ядра при очистке этого индекса, в миллисекундах |
user_time | float8 | Время использования процессора в пользовательском режиме при очистке этого индекса, в миллисекундах |
total_time | float8 | Общее время, затраченное на очистку этого индекса, в миллисекундах |
interrupts | integer | Сколько раз операции очистки для этого индекса были прерваны из-за каких-либо ошибок |
G.4.4.9. Представление pgpro_stats_relcaches #
Представление pgpro_stats_relcaches доступно в версиях Postgres Pro, начиная с 17, когда параметр pgpro_stats.track_relcaches имеет значение true. Представление будет содержать по одной строке для каждой базы данных кластера, показывающей статистику созданий и удалений файла инициализации кеша отношений pg_internal.init. В статистике учитываются только создания и удаления, которые происходили после старта сервера. Количество строк в представлении регулируется параметром конфигурации pgpro_stats.max_relcaches. В таблице ниже описаны столбцы представления.
Таблица G.83. Столбцы pgpro_stats_relcaches
| Столбец | Тип | Описание |
|---|---|---|
dboid | oid | OID базы данных. dboid = 0 соответствует pg_internal.init для общих файлов кластера, не связанных с конкретной базой данных. |
total_creations | int | Число попыток создать файл pg_internal.init для этой базы данных (или для общих файлов кластера при dboid = 0) с момента последнего сброса статистики для этого представления |
successful_creations | int | Сколько раз файл pg_internal.init был успешно создан для этой базы данных (или для общих файлов кластера при dboid = 0) с момента последнего сброса статистики для этого представления |
removals | int | Сколько раз файл pg_internal.init был удалён для этой базы данных (или для общих файлов кластера при dboid = 0) с момента последнего сброса статистики для этого представления. Обратите внимание, что удаления, происходящие при запуске postmaster, не учитываются в статистике. |
stats_since | timestamp | Последнее время сброса этих статистических данных |
Примечание
Поскольку это представление отображает метрики, накопленные с момента последнего сброса статистики, значение successful_creations может оказаться меньше, чем removals.
G.4.5. Типы данных #
G.4.5.1. Тип pgpro_stats_rusage #
Тип pgpro_stats_rusage представляет собой запись, содержащую статистику использования ресурсов во время планирования и выполнения запросов. Поля этого типа показаны в Таблице G.84.
Таблица G.84. Поля pgpro_stats_rusage
| Имя | Тип | Описание |
|---|---|---|
reads | bigint | Количество байт, прочитанное на уровне файловой системы |
writes | bigint | Количество байт, записанное на уровне файловой системы |
user_time | double precision | Время использования процессора в пользовательском режиме |
system_time | double precision | Время использования процессора в режиме ядра |
minflts | bigint | Количество восстановленных страниц (мягких ошибок обращения к страницам) |
majflts | bigint | Количество ошибок обращения к страницам (жёстких) |
nswaps | bigint | Количество обращений к пространству подкачки |
msgsnds | bigint | Количество переданных сообщений IPC |
msgrcvs | bigint | Количество полученных сообщений IPC |
nsignals | bigint | Количество полученных сигналов |
nvcsws | bigint | Количество «добровольных» переключений контекста |
nivcsws | bigint | Количество принудительных переключений контекста |
G.4.6. Функции #
-
pgpro_stats_statements_reset(userid Oid, dbid Oid, queryid bigint, planid bigint, minmax_only boolean) returns timestamp with time zone Функция
pgpro_stats_statements_resetочищает всю статистику, собранную к этому времени модулемpgpro_statsдля заданного пользователя (userid), базы данных (dbid), запроса (queryid) и плана (planid). В случае отсутствия одного из параметров для него подразумевается нулевое значение (неприменимое ограничение) и очищается статистика, соответствующая другим параметрам. Если никакой параметр не задан или все параметры имеют нулевое значение (неприменимое), очищается вся статистика. Вместе с очисткой всей статистики вpgpro_stats_statementsтакже сбрасывается статистика вpgpro_stats_info. Когда для параметраminmax_onlyустановлено значениеtrue, сбрасываются значения только минимального и максимального времени планирования и выполнения оператора (т. е. значения столбцовmin_plan_time,max_plan_time,min_exec_timeиmax_exec_time). Значениеminmax_onlyпо умолчанию —false. Время последнего сброса минимальных/максимальных значений можно увидеть в столбцеminmax_stats_sinceпредставленияpgpro_stats_statements. Функция возвращает время сброса статистики. Это время записывается в полеstats_resetпредставленияpgpro_stats_infoилиminmax_stats_sinceпредставленияpgpro_stats_statements, если соответствующий сброс значений был действительно выполнен. По умолчанию эту функцию могут выполнять только суперпользователи. Другим пользователям можно дать доступ к ней, используяGRANT.Примечание
Поскольку статистика в представлениях
pgpro_stats_vacuum_database,pgpro_stats_vacuum_tablesиpgpro_stats_vacuum_indexesсобирается ядром системы, для её сброса вызовите функциюpg_stat_reset( )(за подробностями обратитесь к Подразделу 27.2.26).-
pgpro_stats_statements(showtext boolean) returns setof record Представление
pgpro_stats_statementsопределяется как результат вызова одноимённой функции. Функциюpgpro_stats_statementsможно также вызывать непосредственно, а с аргументомshowtext := falseможно получить результат без текста запроса (то есть в выходном аргументе, соответствующем столбцу представленияquery, будет выдаваться null). Эта возможность предусмотрена для того, чтобы внешние средства мониторинга могли не загружать каждый раз текст запросов, который может быть довольно объёмным. Средство мониторинга может просто один раз запомнить текст запросов для каждой записи в представлении (как это и делает сам модульpgpro_stats) и затем запрашивать текст для новых запросов только при необходимости. Так как сервер сохраняет текст запросов в файле, при таком подходе постоянное чтение содержимогоpgpro_stats_statementsбудет создавать меньшую нагрузку на ввод-вывод.-
pgpro_stats_statements_filtered(showtext boolean, userid oid, dboid oid, queryid bigint, planid bigint) returns setof record Функция
pgpro_stats_statements_filteredпозволяет отфильтровать статистику, аналогичную выводимой в представленииpgpro_stats_statements, по одному или нескольким полям, задаваемым параметрамиuserid,dbid,queryidиplanid. В случае отсутствия одного из параметров для него подразумевается нулевое значение (неприменимое ограничение) и возвращается статистика, соответствующая другим параметрам. Параметрshowtextпо умолчанию имеет значениеtrue, а задаваяshowtext := false, можно получить результат без текста запроса, как объясняется для функцииpgpro_stats_statements. Поскольку функцияpgpro_stats_statements_filteredвыбирает только нужные записи, она возвращает статистику быстрее, чем следующий запрос:SELECT * FROM pgpro_stats_statements WHERE userid = ? AND dbid = ? AND queryid = ? AND planid = ?;
-
pgpro_stats_info() returns record Представление
pgpro_stats_infoпостроено на базе одноимённой функции, которую пользователи также могут вызывать непосредственно.-
pgpro_stats_totals_reset(type text, id bigint) returns timestamp with timezone Функция
pgpro_stats_totals_resetочищает всю статистику, собранную к этому времени модулемpgpro_statsдля заданного типа (type) и идентификатора (id) объекта. В случае отсутствия параметров или когда параметрtypeравен0, очищается вся статистика. Если в параметреtypeпередаётся корректный тип объекта, то в случае указанияidочищается статистика только для объекта с заданным идентификатором, а в отсутствие такого указания — для всех объектов заданного типа. Если же параметрtypeне задаёт существующий тип объекта, никакая статистика не очищается. Эта функция возвращает время выполнения очистки. По умолчанию эту функцию могут выполнять только суперпользователи. Другим пользователям можно дать доступ к ней, используяGRANT.-
pgpro_stats_totals() returns setof record Представление
pgpro_stats_totalsпостроено на базе одноимённой функции, которую пользователи также могут вызывать непосредственно.-
pgpro_stats_metrics() returns setof record Определяет представление
pgpro_stats_metrics, описанное подробно в Таблице G.78.-
pgpro_stats_get_archiver() returns setof record Определяет представление
pgpro_stats_archiver, описанное подробно в Таблице G.79.-
pgpro_stats_wal_sender_crc_errors() returns bigint В Postgres Pro Enterprise возвращает количество ошибок, обнаруженных процессом-передатчиком WAL, когда параметр
wal_sender_check_crcвключён (on). В Postgres Pro Standard возвращает ноль. Обратите внимание, что при перезапуске кластера этот счётчик сбрасывается до нуля.-
pgpro_stats_vacuum_database(dboid oid) returns setof record Определяет строку представления
pgpro_stats_vacuum_database, которое подробно описано в Таблице G.80, для базы данных, указанной вdboid.-
pgpro_stats_vacuum_tables(dboid oid, relid oid) returns setof record Определяет строку представления
pgpro_stats_vacuum_tables, которое подробно описано в Таблице G.81, для базы данных, указанной вdboid, и таблицы, указанной вreloid. Еслиreloid= 0, возвращается статистика для каждой таблицы в указанной базе данных.-
pgpro_stats_vacuum_indexes(dboid oid, relid oid) returns setof record Определяет строку представления
pgpro_stats_vacuum_indexes, которое подробно описано в Таблице G.82, для базы данных, указанной вdboid, и таблицы, указанной вreloid. Еслиreloid= 0, возвращается статистика для каждого индекса в указанной базе данных.-
pgpro_stats_relcaches(dboid Oid, total_creations int, successful_creations int, removals int, stats_since timestamp) returns setof record Функцию
pgpro_stats_relcachesможно вызывать в версиях Postgres Pro, начиная с 17. Функция определяет строку представленияpgpro_stats_relcaches, которое подробно описано в Таблице G.83, для базы данных, указанной вdboid. Еслиdboid= 0, возвращается строка, соответствующаяpg_internal.initдля общих файлов кластера.-
pgpro_stats_relcaches_reset([dboid oid]) returns timestamp with time zone Функцию
pgpro_stats_relcaches_resetможно вызывать в версиях Postgres Pro, начиная с 17. Функция очищает статистику, возвращаемую представлениемpgpro_stats_relcaches. Если передан параметрdboid> 0, очищается статистика для указанной базы данных. Если передан параметрdboid= 0, очищается статистка поpg_internal.initдля общих файлов кластера. В отсутствие параметраdboidочищается вся статистика. Функция возвращает дату и время сброса статистики.
G.4.6.1. Функции для создания представлений, эмулирующих другие расширения #
В расширении pgpro_stats предусмотрена возможность создания представлений, аналогичных тем, которые создаются расширениями pg_stat_statements и pg_stat_kcache. Можно создать представления pg_stat_statements, pg_stat_statements_info, pg_stat_kcache и pg_stat_kcache_detail. Каждое представление создаётся в версии Postgres Pro, только если оно доступно в расширении pg_stat_statements/pg_stat_kcache для той же версии Postgres Pro/PostgreSQL. Например, представление pg_stat_statements_info создаётся только в версиях Postgres Pro 14 и выше. Эти представления могут быть созданы следующими функциями:
По умолчанию эти функции могут выполнять только суперпользователи. Другим пользователям можно дать доступ к ним, используя GRANT.
Для создания представлений pg_stat_statements* необходимо удалить расширение pg_stat_statements, если оно было установлено ранее, и вызвать функцию:
select pgpro_stats_create_pg_stat_statements_compatible_views();
Для создания представлений pg_stat_kcache* необходимо удалить расширение pg_stat_kcache, если оно было установлено ранее, и вызвать функцию:
select pgpro_stats_create_pg_stat_kcache_compatible_views();
После этого с созданными представлениями можно работать так же, как если бы были установлены соответствующие расширения.
Удалить ранее созданные представления можно обычным способом:
drop view pg_stat_statements; drop view pg_stat_statements_info; drop view pg_stat_kcache; drop view pg_stat_kcache_detail;
G.4.7. Параметры конфигурации #
G.4.7.1. Основные параметры #
pgpro_stats.max(integer) #pgpro_stats собирает статистику только о наиболее часто встречающихся запросах. Чем меньше частота появления некоторого запроса во время работы сервера, тем меньше вероятность его попадания в статистику. Редко возникающие запросы будут почти сразу вытесняться из статистики более частыми. Параметр
pgpro_stats.maxзадаёт максимальное число различных уникальных пар (нормализованный текст запроса, нормализованный текст плана), отслеживаемых pgpro_stats (то есть максимальное число строк в представленииpgpro_stats_statements). Чем выше значение этого параметра, тем о большем числе запросов информация сохранится, но ценой снижения производительности сервера как во время ожидания на блокировках при работе с таблицей статистики в разделяемой памяти, так и при периодической сборке мусора в файле с текстами запросов и планов. Значение по умолчанию — 5000. Этот параметр можно задать только при запуске сервера.pgpro_stats.max_totals(integer) #Параметр
pgpro_stats.max_totalsзадаёт максимальное число объектов, отслеживаемых модулем (то есть максимальное число строк в представленииpgpro_stats_totals). Когда количество наблюдаемых объектов превышает заданное, информация о наименее активно используемых объектах удаляется. Значение по умолчанию — 1000. Этот параметр можно задать только при запуске сервера.pgpro_stats.track(enum) #Параметр
pgpro_stats.trackопределяет, какие операторы будут отслеживаться модулем. Со значениемtopотслеживаются операторы верхнего уровня (те, что непосредственно выполняются клиентами), со значениемallтакже отслеживаются вложенные операторы (например, операторы, вызываемые внутри функций) с уровнем вложенности не более 100, значениеnoneполностью отключает сбор статистики по операторам. Значение по умолчанию —top. Изменять этот параметр могут только суперпользователи.pgpro_stats.track_utility(boolean) #Параметр
pgpro_stats.track_utilityопределяет, будет ли этот модуль отслеживать служебные команды. Служебными командами считаются команды, отличные отSELECT,INSERT,UPDATEиDELETE. Значение по умолчанию —on(вкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.track_planning(boolean) #Параметр
pgpro_stats.track_planningопределяет, будет ли этот модуль отслеживать операции планирования и их длительность. Включение этого параметра может привести к заметному снижению производительности, особенно когда во множестве одновременных сеансов выполняются операторы с одинаковой структурой запросов, в результате чего эти сеансы пытаются одновременно изменить одни и те же записи вpgpro_stats_statements. Значение по умолчанию —off(выкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.track_totals(boolean) #Параметр
pgpro_stats.track_totalsопределяет, будет ли агрегироваться статистика по объектам (на уровне кластера, баз, пользователей и т. д.). Значение по умолчанию —on(вкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.track_cluster(boolean) #Параметр
pgpro_stats.track_clusterпри включённом параметре pgpro_stats.track_totals определяет, будет ли агрегироваться статистика по кластеру в целом. Значение по умолчанию —on(вкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.track_databases(boolean) #Параметр
pgpro_stats.track_databasesпри включённом параметре pgpro_stats.track_totals определяет, будет ли агрегироваться статистика по базам данных. Значение по умолчанию —on(вкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.track_users(boolean) #Параметр
pgpro_stats.track_usersпри включённом параметре pgpro_stats.track_totals определяет, будет ли агрегироваться статистика по пользователям. Значение по умолчанию —on(вкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.track_applications(boolean) #Параметр
pgpro_stats.track_applicationsпри включённом параметре pgpro_stats.track_totals определяет, будет ли агрегироваться статистика по приложениям (по именам, задаваемым в application_name). Значение по умолчанию —on(вкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.track_client_addr(boolean) #Параметр
pgpro_stats.track_client_addrопределяет, будет ли агрегироваться статистика по IP-адресам клиентов. Значение по умолчанию —on(вкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.track_backends(boolean) #Параметр
pgpro_stats.track_backendsопределяет, будет ли агрегироваться статистика по обслуживающим процессам. Значение по умолчанию —on(вкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.track_sessions(boolean) #Параметр
pgpro_stats.track_sessionsопределяет, будет ли агрегироваться статистика по сеансам.Агрегированная статистика по сеансам выводится в представлении
pgpro_stats_totals, причём идентификатор сеанса содержится в столбцеobject_name, поскольку этот идентификатор состоит из двух частей, разделенных точкой, как показано в описании параметра конфигурации log_line_prefix.Значение по умолчанию —
on(вкл.). Изменить этот параметр могут только суперпользователи.pgpro_stats.save(boolean) #Параметр
pgpro_stats.saveопределяет, должна ли статистика операторов сохраняться после перезагрузки сервера. Если он отключён (имеет значениеoff), статистика не сохраняется при остановке сервера и не перезагружается при запуске. Значение по умолчанию —on(вкл.). Этот параметр можно задать только вpostgresql.confили в командной строке сервера.pgpro_stats.plan_format(text) #Параметр
pgpro_stats.plan_formatвыбирает формат плана запроса в выводеEXPLAIN. Возможные значения:text,xml,jsonиyaml. Значение по умолчанию:text. При изменении этого параметра требуется перезапустить сервер.pgpro_stats.enable_profile(boolean) #Параметр
pgpro_stats.enable_profileвключает профилирование событий ожидания по отдельным операторам. Значение по умолчанию:true(вкл.). При изменении этого параметра требуется перезапустить сервер.pgpro_stats.query_sample_rate(float) #Так как pgpro_stats собирает статистику только о наиболее часто встречающихся запросах, а редко встречающиеся запросы в неё не попадают, то есть возможность снизить влияние сбора статистики на производительность сервера. Это выполнимо, потому что через некоторое время после начала сбора практически вся статистика, собранная модулем, будет состоять из запросов, частота появления которых не очень мала, и в дальнейшем множество типов собранных запросов будет меняться слабо, если установлено достаточное значение параметра pgpro_stats.max, а средняя частота появления основной массы частых запросов не претерпевает значительных изменений с периодами, которые превышают время наблюдения. К такому "устоявшемуся" множеству собранных запросов также можно прийти, увеличив время сбора, например, в два раза, но при этом забирая в статистику не каждый запрос, а каждый второй, или же рассматривая каждый запрос, но забирая его в статистику случайно, с некоторой заданной вероятностью. В данном случае — 0.5. Это позволяет заметно снизить нагрузку на сервер за счёт увеличения времени сбора статистики. Реализовать данный подход можно при помощи параметра
pgpro_stats.query_sample_rate. Например, при значенииpgpro_stats.query_sample_rate, равном 0.2 (1/5), за 5 часов работы сервера при выполнении указанных выше условий будет собрана такая же статистика, как и приpgpro_stats.query_sample_rate= 1 за 1 час работы.Можно экспериментально подобрать значение параметра
pgpro_stats.query_sample_rate. Выберите время наблюдения в зависимости от конкретных условий, в которых работает сервер. Например, один час. Посмотрите собранную статистику через час, а затем, не сбрасывая её, ещё через час. Если разница будет в основном не в типе собранных запросов, а в увеличении их количества (calls), то можно безопасно уменьшить значениеpgpro_stats.query_sample_rateв два раза. Если же будет наблюдаться заметная разница в типах собранных запросов, то нужно увеличить время наблюдения и/или параметрpgpro_stats.max.Значение по умолчанию:
1.0. При изменении этого параметра требуется перезапустить сервер.pgpro_stats.profile_period(integer) #Параметр
pgpro_stats.profile_periodзадаёт интервал (в миллисекундах) для сбора информации о событиях ожидания. Значение по умолчанию:10. Изменить этот параметр могут только суперпользователи.pgpro_stats.metrics_buffer_size(integer) #Параметр
pgpro_stats.metrics_buffer_sizeзадаёт размер кольцевого буфера для сбора статистических метрик. Значение по умолчанию:16kB. При изменении этого параметра требуется перезапустить сервер.pgpro_stats.metrics_workers(integer) #Параметр
pgpro_stats.metrics_workersзадаёт количество рабочих процессов, которые будут собирать статистические метрики. Если этот параметр больше или равен 2, один из рабочих процессов будет главным, распределяющим запросы между всеми остальными. Если количество рабочих процессов ограничивается одним, он будет перезапускаться для подключения к разным базам данных. Когда этот параметр равен0, сбор метрик отключается. Значение по умолчанию:2. При изменении этого параметра требуется перезапустить сервер.pgpro_stats.stats_temp_directory(string) #Параметр
pgpro_stats.stats_temp_directoryзадаёт каталог с внешним файлом для хранения текстов запросов. Это может быть путь от каталога данных или абсолютный путь. При изменении этого параметра требуется перезапустить сервер.pgpro_stats.track_relcaches(boolean) #pgpro_stats.track_relcachesвключает сбор статистики созданий и удалений файла инициализации кеша отношенийpg_internal.init, доступной в представленииpgpro_stats_relcaches. Значение по умолчанию —false. При включении этого параметра требуется перезапустить сервер.pgpro_stats.max_relcaches(integer) #pgpro_stats.max_relcachesопределяет максимальное количество строк представленияpgpro_stats_relcaches, т. е. количество баз данных, отслеживаемых в статистике созданий и удаленийpg_internal.init, плюс один (со статистикой поpg_internal.initдля общих файлов кластера). При превышении этого значения информация по базам данных, которая в последний раз обновлялась раньше всего, вытесняется.pgpro_stats.enable_warnings(boolean) #pgpro_stats.enable_warningsдобавляет предупреждение в полеplanпредставленияpgpro_stats_statements, если план был выполнен с отсечением секций. Текст предупреждения: «pgpro_stats warning: Some subplans could be pruned based on actual parameter values. This output reflects one possible execution plan. (Предупреждение pgpro_stats: Некоторые подпланы могли быть отсечены на основе имеющихся значений параметров. Этот вывод отражает один возможный план выполнения.)» Значение по умолчанию —false. Если этот параметр включён, план в Примере G.1 будет содержать предупреждение.
G.4.7.2. Параметры, определяющие метрики #
Следующие параметры предназначены для определения дополнительных метрик, которые будет собирать pgpro_stats. Номер N в имени параметра служит уникальным идентификатором метрики, к которой будет применяться задаваемое значение; он должен быть положительным и уникальным среди всех метрик.
Если вы добавляете параметры для определения новой метрики, необходимо перезапустить сервер, чтобы это определение начало действовать.
pgpro_stats.metric_(N_nametext)Имя метрики с номером
N. Это имя будет выводиться в столбцеmetric_nameпредставленияpgpro_stats_metrics.pgpro_stats.metric_(N_querytext)Текст запроса, определяющий значение собираемой метрики.
pgpro_stats.metric_(N_periodinteger)Интервал, с которым будет собираться метрика
N, в миллисекундах. Значение по умолчанию: 60000 mspgpro_stats.metric_(N_dbtext)Список баз данных, в которых будет собираться метрика
N. Имена баз данных должны разделяться запятыми. Чтобы выбрать все базы данных в кластере, за исключением баз-шаблонов, можно указать значение*. Если вы также хотите анализировать запросы в базах-шаблонах, их нужно перечислить явно.pgpro_stats.metric_(N_usertext)Имя пользователя, от имени которого будет собираться метрика
N. Этот пользователь должен иметь доступ к базе данных, в которой будет выполняться запрос для сбора метрики.
G.4.8. Трассировка сеансов приложений #
В расширении pgpro_stats реализована трассировка сеансов приложений. Она основана на фильтрах, которые запускают протоколирование выполнения запросов, соответствующих условиям фильтрации. Запросы и вывод EXPLAIN для них записываются в так называемые файлы трассировки, указанные пользователем, или в файл системного журнала (если файл трассировки не указан). Фильтры хранятся в таблице, находящейся в общей памяти. Строки этой таблицы соответствуют фильтрам, а столбцы содержат условия фильтрации и параметры, с которыми вызывается EXPLAIN (за подробностями обратитесь к EXPLAIN). Чтобы начать трассировку запросов, следует заполнить эту таблицу фильтрами.
Как только администратор базы данных добавит фильтр в каком-либо сеансе, все последующие выполнения запросов, соответствующих условиям фильтра, будут трассироваться всеми сеансами экземпляра СУБД без необходимости перезапуска сервера. Другими словами, фильтры можно добавлять, удалять или изменять «на лету», и трассировка с этими фильтрами сразу же начнётся для существующих и будущих сеансов.
Примечание
Операции добавления, удаления или изменения фильтров не являются транзакционными. Изменения таблицы фильтров не отменяются вместе с транзакцией, в которой эти изменения были сделаны.
Столбцы таблицы, в которой хранятся фильтры, также называются атрибутами фильтров. Они показаны в Таблице G.85.
Таблица G.85. Атрибуты фильтров
| Имя | Тип | Описание |
|---|---|---|
filter_id | integer | Уникальный идентификатор фильтра, который автоматически присваивается фильтру при его создании, нумерация начинается с 1. |
active | boolean | При значении false фильтр не активен, то есть запросы, соответствующие этому фильтру, не регистрируются. По умолчанию: true. |
alias | name | Имя фильтра, которое можно указать для удобства. Показывается только в выводе функции pgpro_stats_trace_show(). По умолчанию: пустая строка. |
tracefile | name | Имя файла трассировки, в котором регистрируются запросы, соответствующие фильтру, и вывод EXPLAIN для них. Если это имя не указано, запись ведётся в системный журнал с уровнем, указанным в pgpro_stats.trace_log_level. Файлы трассировки создаются в каталоге и имеют расширение trace. |
pid | integer | Идентификатор обслуживающего процесса, который выполняет этот оператор |
database_name | name | Имя базы данных, в которой выполняется оператор |
client_addr | name | IP-адрес клиента, подключённого к этому обслуживающему процессу |
application_name | name | Имя приложения, вызвавшего выполнение оператора |
username | name | Имя пользователя, выполняющего оператор |
queryid | bigint | Внутренний хеш-код, вычисленный на основании дерева разбора оператора |
planid | bigint | Внутренний хеш-код, вычисленный на основании дерева плана оператора |
duration | float8 | Время, затраченное на планирование и выполнение оператора, в миллисекундах |
plan_time | float8 | Время, затраченное на планирование оператора, в миллисекундах |
exec_time | float8 | Время, затраченное на выполнение оператора, в миллисекундах |
user_time | float8 | Время использования процессора в пользовательском режиме, затраченное на планирование и выполнение оператора |
system_time | float8 | Время использования процессора в режиме ядра, затраченное на планирование и выполнение оператора |
rows | int8 | Общее число строк, полученных или затронутых оператором |
shared_blks_hit | int8 | Общее число попаданий разделяемых блоков в кеш для данного оператора |
shared_blks_read | int8 | Общее число разделяемых блоков, прочитанных данным оператором |
shared_blks_fetched | int8 | Общее число разделяемых блоков, прочитанных данным оператором из буферов |
shared_blks_dirtied | int8 | Общее число разделяемых блоков, «загрязнённых» данным оператором |
shared_blks_written | int8 | Общее число разделяемых блоков, записанных данным оператором |
local_blks_hit | int8 | Общее число попаданий локальных блоков в кеш для данного оператора |
local_blks_read | int8 | Общее число локальных блоков, прочитанных данным оператором |
local_blks_fetched | int8 | Общее число локальных блоков, прочитанных данным оператором из буферов |
local_blks_dirtied | int8 | Общее число локальных блоков, «загрязнённых» данным оператором |
local_blks_written | int8 | Общее число локальных блоков, записанных данным оператором |
temp_blks_read | int8 | Общее число временных блоков, прочитанных данным оператором |
temp_blks_written | int8 | Общее число временных блоков, записанных данным оператором |
wal_bytes | numeric | Общий объём WAL (в байтах), сгенерированный при выполнении оператора |
total_wait_time | float8 | Общее время, затраченное на ожидание при выполнении этого оператора |
total_inval_msgs | bigint | Общее число сообщений аннулирования кеша, выданных при выполнении оператора (если это поддерживает сервер) |
explain_analyze | boolean | При значении true вывод EXPLAIN будет протоколироваться с параметром ANALYZE. Значение по умолчанию определяется параметром конфигурации pgpro_stats.explain_analyze_default. |
explain_verbose | boolean | При значении true вывод EXPLAIN будет протоколироваться с параметром VERBOSE. Значение по умолчанию определяется параметром конфигурации pgpro_stats.explain_verbose_default. |
explain_costs | boolean | При значении true вывод EXPLAIN будет протоколироваться с параметром COSTS. Значение по умолчанию определяется параметром конфигурации pgpro_stats.explain_costs_default. |
explain_settings | boolean | При значении true вывод EXPLAIN будет протоколироваться с параметром SETTINGS. Значение по умолчанию определяется параметром конфигурации pgpro_stats.explain_settings_default. |
explain_buffers | boolean | При значении true вывод EXPLAIN будет протоколироваться с параметром BUFFERS. Значение по умолчанию определяется параметром конфигурации pgpro_stats.explain_buffers_default. |
explain_wal | boolean | При значении true вывод EXPLAIN будет протоколироваться с параметром WAL. Значение по умолчанию определяется параметром конфигурации pgpro_stats.explain_wal_default. |
explain_timing | boolean | При значении true вывод EXPLAIN будет протоколироваться с параметром TIMING. Значение по умолчанию определяется параметром конфигурации pgpro_stats.explain_timing_default. |
explain_format | text | Значение параметра FORMAT протоколируемой команды EXPLAIN, которое может быть TEXT, XML, JSON или YAML. Значение по умолчанию определяется параметром конфигурации pgpro_stats.plan_format. |
time_info | boolean | При значении true добавляет дополнительную информацию в вывод трассировки сеанса в формате, установленном атрибутом explain_format: pid, duration в миллисекундах, start time — время начала выполнения запроса и stop time — время окончания выполнения запроса. Вывод трассировки с дополнительной информацией показан в Примере G.3. |
Атрибуты фильтров можно разделить на следующие группы:
Управляющие атрибуты, от
filter_idдоtracefileв Таблица G.85.Идентифицирующие атрибуты, от
pidдоplanidв Таблица G.85.Пороговые атрибуты, от
durationдоtotal_inval_msgsв Таблица G.85.Атрибуты, которые управляют выводом в файл трассировки или файл системного журнала и не влияют на фильтрацию. В основном они определяют параметры
EXPLAIN. Это атрибуты, начинающиеся сexplain_analyzeи до конца Таблицы G.85.
Выполнение запроса будет трассироваться, если выполняются оба следующих условия:
Для всех указанных идентифицирующих атрибутов идентификации фильтра значения соответствующих характеристик запроса совпадают со значениями этих атрибутов.
Для всех указанных пороговых атрибутов фильтра значения соответствующих характеристик запроса больше или равны пределам, указанным в этих атрибутах.
Можно не присваивать значения атрибутам. Для всех атрибутов, кроме active, можно также явно присвоить значение NULL. Если значение управляющего атрибута не определено или явно задан NULL, этому атрибуту будет присвоено значение по умолчанию, показанное в Таблица G.85. Для идентифицирующих и пороговых атрибутов неопределённые значения или NULL означают, что запросы не будут фильтроваться по соответствующей характеристике. Если для всех идентифицирующих и пороговых атрибутов не определено ни одного значения, все запросы считаются соответствующими этому фильтру и будут регистрироваться. Если атрибуты, задающие параметры EXPLAIN, не определены, будут использоваться значения по умолчанию, определённые параметрами конфигурации (за подробностями обратитесь к Подраздел G.4.8.2).
Предупреждение
Хотя при задании фильтра можно устанавливать значения для любой комбинации атрибутов фильтра, имейте в виду, что слишком общий фильтр приведёт к чрезмерному увеличению размера файла трассировки и заметно повлияет на производительность, поскольку основные издержки связаны с записью в файл трассировки, а не с проверкой условий фильтра.
G.4.8.1. Функции трассировки сеансов #
Специальные функции позволяют создавать, изменять и удалять фильтры запросов:
-
pgpro_stats_trace_insert(VARIADIC "any") returns integer Добавляет фильтр в список фильтров трассировки сеанса. Фильтр должен быть передан как последовательность чередующихся пар ключ-значение, где ключ — это имя атрибута фильтра из Таблица G.85, за исключением
filter_id. Например:pgpro_stats_trace_insert('pid', 42, 'database_name', 'main', 'explain_analyze', true)Пары ключ-значение позиционно независимы: они могут быть указаны в любом порядке, независимо от порядка атрибутов в Таблица G.85. Некоторые атрибуты могут отсутствовать в последовательности. Таким атрибутам будут назначены значения по умолчанию. Возвращает уникальный
filter_id, который функция назначает добавленному фильтру.Если какой-либо атрибут фильтра встречается в передаваемой последовательности более одного раза, функция завершится ошибкой.
Обратите внимание, что функция может завершиться нормально, но вернуть NULL, если фильтр не был добавлен. Это происходит, например, если один из переданных атрибутов фильтра имеет значение NULL.
-
pgpro_stats_trace_update(filter_id integer, VARIADIC "any") returns boolean Изменяет фильтр трассировки сеанса, определённый
filter_id. Атрибуты фильтра для изменения должны передаваться как последовательность чередующихся пар ключ-значение, где ключ — это имя атрибута фильтра из Таблица G.85, за исключениемfilter_id. Пары ключ-значение позиционно независимы: они могут быть указаны в любом порядке, независимо от порядка атрибутов в Таблица G.85. Атрибуты фильтра, значения которых не указаны явно, не будут изменены. Значение NULL для идентифицирующих и пороговых атрибутов сбрасывает значения этих атрибутов, что означает, что запрос будет соответствовать условиям изменённого фильтра независимо от соответствующих характеристик. Возвращаетtrueв случае успеха иfalseв противном случае.Если какой-либо атрибут фильтра встречается в передаваемой последовательности более одного раза, функция завершится ошибкой.
-
pgpro_stats_trace_delete(filter_id integer) returns boolean Удаляет фильтр трассировки сеанса, заданный параметром
filter_id. При успешном удалении возвращаетtrue, в противном случае —false.-
pgpro_stats_trace_reset() returns integer Удаляет все фильтры трассировки сеансов. Возвращает количество удалённых фильтров. По умолчанию эту функцию могут выполнять только суперпользователи. Другим пользователям можно дать доступ к ней, используя
GRANT.-
pgpro_stats_trace_show() returns setof record Отображает содержимое таблицы фильтров, столбцы которой показаны в Таблице G.85.
G.4.8.2. Параметры конфигурации трассировки сеансов #
Следующие параметры могут использоваться для конфигурации протоколирования трассировки сеансов. Обратите внимание, что параметры pgpro_stats.explain_*_default определяют поведение протоколирования, когда соответствующие атрибуты фильтра explain_* (из Таблица G.85) не указаны или для них явно заданы значения NULL.
pgpro_stats.explain_analyze_default(boolean) #При значении
trueвыводEXPLAINбудет протоколироваться с параметромANALYZE, в противном случае (false) — без него. По умолчанию:false. Изменить этот параметр могут только суперпользователи.pgpro_stats.explain_verbose_default(boolean) #При значении
trueвыводEXPLAINбудет протоколироваться с параметромVERBOSE, в противном случае (false) — без него. По умолчанию:false. Изменить этот параметр могут только суперпользователи.pgpro_stats.explain_costs_default(boolean) #При значении
trueвыводEXPLAINбудет протоколироваться с параметромCOSTS, в противном случае (false) — без него. По умолчанию:true. Изменить этот параметр могут только суперпользователи.pgpro_stats.explain_settings_default(boolean) #При значении
trueвыводEXPLAINбудет протоколироваться с параметромSETTINGS, в противном случае (false) — без него. По умолчанию:false. Изменить этот параметр могут только суперпользователи.pgpro_stats.explain_buffers_default(boolean) #При значении
trueвыводEXPLAINбудет протоколироваться с параметромBUFFERS, в противном случае (false) — без него. По умолчанию:false. Изменить этот параметр могут только суперпользователи.pgpro_stats.explain_wal_default(boolean) #При значении
trueвыводEXPLAINбудет протоколироваться с параметромWAL, в противном случае (false) — без него. По умолчанию:false. Изменить этот параметр могут только суперпользователи.pgpro_stats.explain_timing_default(boolean) #При значении
trueвыводEXPLAINбудет протоколироваться с параметромTIMING, в противном случае (false) — без него. По умолчанию:true. Изменить этот параметр могут только суперпользователи.pgpro_stats.trace_log_level(enum) #Определяет уровень детализации, с которым вывод
EXPLAINбудет записываться в системный файл журнала (если файл трассировки не указан). Допустимые значения:DEBUG,INFO,NOTICE,WARNINGиLOG. Значение по умолчанию:LOG.pgpro_stats.trace_query_text_size(int) #Определяет максимальный размер текста запроса в выводе трассировки сеансов, в килобайтах. Если размер текста запроса в килобайтах больше, запрос обрезается до максимального размера. Если параметр не задан, используется значение по умолчанию ноль, которое означает, что в вывод включаются полные тексты запросов.
G.4.8.3. Примеры, относящиеся к трассировке сеансов #
Пример G.2. Использование функций трассировки сеансов
Добавьте фильтр first:
SELECT pgpro_stats_trace_insert('alias', 'first', 'pid', pg_backend_pid(), 'explain_analyze', true); Добавьте фильтр second и укажите протоколирование в файл трассировки second_tf.trace:
SELECT pgpro_stats_trace_insert('alias', 'second', 'database_name', current_database(), 'explain_costs', false, 'tracefile', 'second_tf');Таблицу с фильтрами можно посмотреть следующим образом:
\x auto SELECT * FROM pgpro_stats_trace_show();
-[ RECORD 1 ]-------+---------- filter_id | 1 active | t alias | first tracefile | pid | 243183 database_name | client_addr | application_name | username | queryid | planid | duration | plan_time | exec_time | user_time | system_time | rows | shared_blks_hit | shared_blks_read | shared_blks_fetched | shared_blks_dirtied | shared_blks_written | local_blks_hit | local_blks_read | local_blks_fetched | local_blks_dirtied | local_blks_written | temp_blks_read | temp_blks_written | wal_bytes | total_wait_time | total_inval_msgs | explain_analyze | t explain_verbose | explain_costs | explain_settings | explain_buffers | explain_wal | explain_timing | explain_format | time_info | f -[ RECORD 2 ]-------+---------- filter_id | 2 active | t alias | second tracefile | second_tf pid | database_name | postgres client_addr | application_name | username | queryid | planid | duration | plan_time | exec_time | user_time | system_time | rows | shared_blks_hit | shared_blks_read | shared_blks_fetched | shared_blks_dirtied | shared_blks_written | local_blks_hit | local_blks_read | local_blks_fetched | local_blks_dirtied | local_blks_written | temp_blks_read | temp_blks_written | wal_bytes | total_wait_time | total_inval_msgs | explain_analyze | explain_verbose | explain_costs | f explain_settings | explain_buffers | explain_wal | explain_timing | explain_format | time_info | f
Следующий запрос соответствует условиям обоих фильтров, поэтому он должен быть записан в файл системного журнала и в указанный файл трассировки:
SELECT 1 AS result;
Вывод в файл системного журнала выглядит так:
-- :: MSK [] LOG: Filter 1 triggered explain of the plan: Query Text: SELECT 1 AS result; Result (cost=0.00..0.01 rows=1 width=4) (actual time=0.003..0.003 rows=1 loops=1)
Ниже приведён вывод файла трассировки second_tf.trace:
Query Text: SELECT 1 AS result; Result
Удалите первый фильтр:
SELECT pgpro_stats_trace_delete(1);
Также измените значение pid на 2 для второго фильтра
SELECT pgpro_stats_trace_update(2, 'pid', 2);
При выполнении запроса
SELECT 2 AS result;
он не записывается в second_tf.trace.
Удалите все фильтры из таблицы:
SELECT pgpro_stats_trace_reset();
Пример G.3. Вывод трассировки сеанса с time_info = true
Следующий пример показывает вывод трассировки сеанса в формате JSON при time_info = true:
{
"Pid": 123456,
"Duration ms": 0.094691,
"Start time": "2025-01-12 15:39:27.580447+03",
"Stop time": "2025-01-12 15:39:27.587802+03",
"Query Text": "SELECT 2 AS Result;",
"Plan": {
"Node Type": "Result",
"Parallel Aware": false,
"Async Capable": false,
"Startup Cost": 0.00,
"Total Cost": 0.01,
"Plan Rows": 1,
"Plan Width": 4
}
}
G.4.9. Метрики аннулирования кеша #
Помимо прочего, pgpro_stats может собирать статистику аннулирования кеша. Представленная в этом разделе общая информация поможет лучше понимать показатели, связанные с этой статистикой.
У каждого обслуживающего процесса есть свой локальный кеш, что позволяет минимизировать обращения к метаинформации таблиц, в частности к системным каталогам. Если какой-либо обслуживающий процесс изменяет метаинформацию некоторого объекта, она должна обновиться в кешах других обслуживающих процессов. Для этого первый обслуживающий процесс отправляет сообщение аннулирования в специальную очередь для таких сообщений.
Все обслуживающие процессы получают сообщения аннулирования из очереди. Если объект, для которого получено сообщение аннулирования, находится в кеше, его метаданные в кеше обновляются, иначе это сообщение просто игнорируется. В pgpro_stats значения большинства счётчиков сообщений аннулирования, если явно не указано иное, увеличиваются, когда обслуживающие процессы только генерируют сообщения, которые попадут в очередь после фиксации соответствующей транзакции. Обратите внимание, что при откате транзакции счётчики не уменьшаются, хотя сообщения в этом случае не доходят до очереди и аннулирование не производится.
Когда обслуживающий процесс, добавляющий сообщения в очередь, обнаруживает, что размер очереди достиг некоторого предела, он запускает очистку, удаляя сообщения, уже обработанные всеми обслуживающими процессами. Если какие-то обслуживающие процессы не успевают обрабатывать сообщения и, таким образом, задерживают очистку, им передаётся сигнал, чтобы они сбросили свои кеши.
G.4.9.1. Представление pgpro_stats_inval_status #
Представление pgpro_stats_inval_status содержит одну строку, показывающую текущее состояние глобальной очереди аннулирования кеша. Столбцы представления показаны в Таблице G.86.
Таблица G.86. Столбцы pgpro_stats_inval_status
| Имя | Тип | Описание |
|---|---|---|
num_inval_messages | int8 | Текущее число сообщений аннулирования в очереди |
num_inval_queue_cleanups | int8 | Количество очисток очереди аннулирования, выполненных во избежание её переполнения |
num_inval_queue_resets | int4 | Число операций сброса кеша для обслуживающих процессов, не успевающих обрабатывать сообщения достаточно быстро |
В работающей системе num_inval_messages обычно имеет значение около 4000, то есть очередь почти полностью заполнена. Увеличение num_inval_queue_cleanups говорит о том, что в очередь поступает много сообщений аннулирования кеша. Обычно счётчик num_inval_queue_resets не увеличивается, а его увеличение свидетельствует о слишком быстром поступлении таких сообщений или о задержках в их обработке со стороны обслуживающих процессов. Отслеживание значений num_inval_queue_cleanups и num_inval_queue_resets в некоторых случаях может позволить обнаружить проблемные обслуживающие процессы, как описано ниже.
Если на протяжении некоторого времени счётчик num_inval_queue_cleanups заметно увеличивается, а num_inval_queue_resets — нет, это говорит о том, что обслуживающие процессы обрабатывают сообщения аннулирования медленнее, чем они генерируются, но всё же достаточно быстро для того, чтобы очередь не переполнялась.
Если на протяжении некоторого времени счётчик num_inval_queue_cleanups значительно не увеличивается, а счётчик num_inval_queue_resets — увеличивается, это определённо указывает на задержку обработки сообщений обслуживающими процессами. Какие именно обслуживающие процессы виноваты в задержке, позволяет определить столбец cache_resets представления pgpro_stats_totals.
Если же на протяжении некоторого времени оба счётчика значительно увеличиваются, это указывает на то, что обслуживающие процессы обрабатывают сообщения аннулирования настолько медленно, что происходит переполнение очереди. Какие именно процессы задерживают обработку сообщений, позволяет определить столбец cache_reset представления pgpro_stats_total. Что является причиной увеличения значения num_inval_queue_resets, большая скорость генерирования сообщений или слишком медленная их обработка, непосредственно определить нельзя. Однако можно проанализировать счётчик total из представления pgpro_stats_inval_msgs. Если в данном интервале времени счётчик изменился примерно на ту же величину, что и в предыдущем интервале той же длительности, увеличение счётчиков определённо вызвано задержками обслуживающих процессов.
Представление pgpro_stats_inval_status можно определить с помощью функции:
-
pgpro_stats_inval_status() returns record Определяет представление
pgpro_stats_inval_status, описанное подробно в Таблице G.86.
G.4.9.2. Тип pgpro_stats_inval_msgs #
Представления pgpro_stats_statements и pgpro_stats_totals для каждого соответствующего объекта показывают запись типа pgpro_stats_inval_msgs со счётчиками сообщений аннулирования кеша. Поля этой записи показаны в Таблице G.87.
Таблица G.87. Поля pgpro_stats_inval_msgs
| Имя | Тип | Описание |
|---|---|---|
total | bigint | Общее число сообщений аннулирования |
catcache | bigint | Число сообщений избирательного аннулирования кеша каталога |
catalog | bigint | Число сообщений полного аннулирования кеша каталога |
relcache | bigint | Число сообщений избирательного аннулирования кеша отношений |
relcache_all | bigint | Число сообщений полного аннулирования кеша отношений |
smgr | bigint | Число сообщений, вызывающих аннулирование открытых файлов отношений. Увеличивается, когда сообщения попадают в очередь. |
relmap | bigint | Число сообщений аннулирования кеша карты отношений. Увеличивается, когда сообщения отправляются в очередь. |
snapshot | bigint | Число сообщений аннулирования снимков каталога |
G.4.10. Авторы #
Postgres Professional, Москва, Россия
G.4. pgpro_stats — a means for tracking planning and execution statistics of all SQL statements executed by a server #
The pgpro_stats extension provides a means for tracking planning and execution statistics of all SQL statements executed by a server. It is based on the pg_stat_statements module and provides the following additional functionality:
Storing query plans in addition to query statements.
Configuring sample rate for statistics collection to reduce overhead.
Calculating wait event statistics for executed queries.
Calculating resource usage statistics of statement planning and execution.
Calculating cache invalidation statistics.
Calculating additional archiver statistics.
Providing an interface to statistics about vacuuming databases, tables, and indexes collected by the core system.
Tracing of application sessions.
Creating views that emulate other extensions.
Note
When the server gets shut down, pgpro_stats saves the collected statistics to two dump files on disk in the format that depends on the number and order of columns in the pgpro_stats_statements and pgpro_stats_totals views. If this format has changed in a new pgpro_stats version, during the first server restart after upgrading the extension, the saved statistics will fail to be read with an error reported to the log:
LOG: pgpro_stats: could not load statements data file of obsolete format "pg_stat/pgpro_stats.stat"
or
LOG: pgpro_stats: could not load statements data file of obsolete format "pg_stat/pgpro_stats_totals.stat"
The contents of the files will be ignored, and respective statistics will be nullified. To learn whether the format has changed, see the Release Notes for pgpro_stats version being installed. To retain the previously collected statistics, download them as CSV files before upgrading.
The background information, along with views and types, related to calculating cache invalidation statistics is provided in a separate section Section G.4.9.
G.4.1. Limitations #
pgpro_statscan sometimes fail to match identical parameters in the query statement and the corresponding query plan.Some SPI queries are not included into statistics.
Texts and plans of some SPI queries are not normalized.
pgpro_statsis incompatible with pg_stat_statements, as well as other extensions that use parser, planner, or executor hooks to modify parse and plan trees and execution of the queries. Moreover, if bothpgpro_statsand pg_stat_statements are on the list ofshared_preload_libraries, the database server will not start. Note also that in order to dump the final versions of the queries and plans,pgpro_statsshould be the last on the list ofshared_preload_libraries, but some existing extensions may not work at all unless they are the last on this list.pgpro_statsmay not work correctly with third-party extensions that produceCustomScanandForeignScannodes.
G.4.2. Installation and Setup #
pgpro_stats is provided with Postgres Pro Standard as a separate pre-built package pgpro-stats-std-18 (for the detailed installation instructions, see Chapter 16). Once you have pgpro_stats installed, complete the following steps to enable pgpro_stats:
Add
pgpro_statsto the shared_preload_libraries parameter in thepostgresql.conffile:shared_preload_libraries = 'pgpro_stats'
Restart the Postgres Pro Standard instance for the changes to take effect.
Once the server is reloaded,
pgpro_statsstarts tracking statistics across all databases of the cluster. If required, you can change the scope of statistics collection or disable it altogether usingpgpro_statsconfiguration parameters.To access the collected statistics, you have to create
pgpro_statsextension:CREATE EXTENSION pgpro_stats;
In addition, query identifier calculation must be enabled in order for pgpro_stats to be active, which is done automatically if compute_query_id is set to auto or on, or any third-party module that calculates query identifiers is loaded.
G.4.3. Usage #
G.4.3.1. Collecting Statistics on Query Statements and Plans #
Once installed, the pgpro_stats extension starts collecting statistics on the executed statements. The collected data is similar to the one provided by pg_stat_statements, but also includes information on query plans and wait events for each query type. The statistics is saved into an in-memory ring buffer and is accessible through the pgpro_stats_statements view.
By default, pgpro_stats collects statistics on all the executed statements that satisfy the pgpro_stats.track and pgpro_stats.track_utility settings. If performance is a concern, you can set a sample rate for queries using the pgpro_stats.query_sample_rate parameter, and pgpro_stats will randomly select queries for statistics calculation at the specified rate.
To collect statistics on wait events, pgpro_stats uses time-based sampling. Wait events are sampled at the time interval specified by the pgpro_stats.profile_period parameter, which is set to 10ms by default. If the sampling shows that the process is waiting, the pgpro_stats.profile_period value is added to the wait event duration. Thus, time estimation for each wait event remains valid even if the pgpro_stats.profile_period parameter value has changed. If you are not interested in wait event statistics, you can disable wait event sampling by setting the pgpro_stats.enable_profile parameter to false.
pgpro_stats_statements.plans and pgpro_stats_statements.calls aren't always expected to match because planning and execution statistics are updated at their respective end phase, and only for successful operations. For example, if a statement is successfully planned but fails during the execution phase, only its planning statistics will be updated. If planning is skipped because a cached plan is used, only its execution statistics will be updated.
As an example, let's create a table with some random data and build an index on this table:
CREATE TABLE test AS (SELECT i, random() x FROM generate_series(1,1000000) i); CREATE INDEX test_x_idx ON test (x);
Now run the following query several times using different values for :x_min and :x_max:
select * from test where x >= :x_min and x <= :x_max;
The collected statistics should appear in the pgpro_stats_statements view:
SELECT queryid, query, planid, plan, wait_stats FROM pgpro_stats_statements WHERE query LIKE 'select * from test where%';
-[ RECORD 1 ]----------------------------------------------------------------------------------------------------------
queryid | 1109491335754870054
query | select * from test where x >= $1 and x <= $2
planid | 8287793242828473388
plan | Gather
| Output: i, x
| Workers Planned: 2
| -> Parallel Seq Scan on public.test
| Output: i, x
| Filter: ((test.x >= $3) AND (test.x <= $4))
|
wait_stats | {"IO": {"DataFileRead": 10}, "IPC": {"BgWorkerShutdown": 10}, "Total": {"IO": 10, "IPC": 10, "Total": 20}}
-[ RECORD 2 ]----------------------------------------------------------------------------------------------------------
queryid | 1109491335754870054
query | select * from test where x >= $1 and x <= $2
planid | -9045072158333552619
plan | Bitmap Heap Scan on public.test
| Output: i, x
| Recheck Cond: ((test.x >= $3) AND (test.x <= $4))
| -> Bitmap Index Scan on test_x_idx
| Index Cond: ((test.x >= $5) AND (test.x <= $6))
|
wait_stats | {"IO": {"DataFileRead": 40}, "Total": {"IO": 40, "Total": 40}}
-[ RECORD 3 ]----------------------------------------------------------------------------------------------------------
queryid | 1109491335754870054
query | select * from test where x >= $1 and x <= $2
planid | -1062789671372193287
plan | Seq Scan on public.test
| Output: i, x
| Filter: ((test.x >= $3) AND (test.x <= $4))
|
wait_stats | NULL
-[ RECORD 4 ]----------------------------------------------------------------------------------------------------------
queryid | 1109491335754870054
query | select * from test where x >= $1 and x <= $2
planid | -1748292253893834280
plan | Index Scan using test_x_idx on public.test
| Output: i, x
| Index Cond: ((test.x >= $3) AND (test.x <= $4))
|
wait_stats | NULL
G.4.3.2. Monitoring Custom Metrics #
With pgpro_stats, you can define custom metrics to be monitored. The collected data will be saved into an in-memory ring buffer and then sent to a monitoring system. Unlike direct polling of a database by a monitoring system that can lose some data if the connection is interrupted, this approach allows to get all the collected data regardless of connection issues, as long as this data is still available in the ring buffer.
To set up a custom metric to collect, do the following:
For each metric, define all configuration parameters listed in Section G.4.7.2. You must specify a unique numeric identifier of each metric in the parameter names.
For example, to monitor index bloating each 60 seconds, you can define a new metric by setting metrics-related parameters as follows:
pgpro_stats.metric_1_name = index_bloat pgpro_stats.metric_1_query = 'select iname, ibloat, ipages from bloat' pgpro_stats.metric_1_db = 'postgres' pgpro_stats.metric_1_user = postgres pgpro_stats.metric_1_period = '60s'
Restart the server.
pgpro_statsstarts collecting statistics on executed statements and saves it into the ring buffer, and the collected data appears in thepgpro_stats_metricsview:SELECT * FROM pgpro_stats_metrics;
If required, set up data export to a monitoring system of your choice.
G.4.4. Views #
G.4.4.1. The pgpro_stats_statements View #
The statistics gathered by the module are made available via a view named pgpro_stats_statements. This view contains one row for each distinct database ID, user ID, query ID, and plan ID (up to the maximum number of distinct statements that the module can track). The columns of the view are shown in Table G.75.
Table G.75. pgpro_stats_statements Columns
| Name | Type | References | Description |
|---|---|---|---|
userid | oid | | OID of user who executed the statement |
dbid | oid | | OID of database in which the statement was executed |
toplevel | bool | True if the query was executed as a top-level statement (always true if pgpro_stats.track is set to top) | |
queryid | bigint | Hash code to identify the normalized query | |
planid | bigint | Hash code to identify the normalized statement's plan | |
query | text | Text of a representative statement | |
plan | text | The text of the query plan, in the format defined by the pgpro_stats.plan_format configuration parameter | |
plans | int8 | Number of times the statement was planned (if pgpro_stats.track_planning is enabled, otherwise zero) | |
total_plan_time | float8 | Total time spent planning the statement, in milliseconds (if pgpro_stats.track_planning is enabled, otherwise zero). | |
min_plan_time | float8 | Minimum time spent planning the statement, in milliseconds (if pgpro_stats.track_planning is enabled, otherwise zero) | |
max_plan_time | float8 | Maximum time spent planning the statement, in milliseconds (if pgpro_stats.track_planning is enabled, otherwise zero) | |
mean_plan_time | float8 | Mean time spent planning the statement, in milliseconds (if pgpro_stats.track_planning is enabled, otherwise zero) | |
stddev_plan_time | float8 | Population standard deviation of time spent planning the statement, in milliseconds (if pgpro_stats.track_planning is enabled, otherwise zero) | |
plan_rusage | pgpro_stats_rusage | Resource usage statistics of the statement planning. | |
calls | int8 | Number of times the statement was executed | |
total_exec_time | float8 | Total time spent executing the statement, in milliseconds | |
min_exec_time | float8 | Minimum time spent executing the statement, in milliseconds | |
max_exec_time | float8 | Maximum time spent executing the statement, in milliseconds | |
mean_exec_time | float8 | Mean time spent executing the statement, in milliseconds | |
stddev_exec_time | float8 | Population standard deviation of time spent executing the statement, in milliseconds | |
exec_rusage | pgpro_stats_rusage | Resource usage statistics of the statement execution. | |
rows | int8 | Total number of rows retrieved or affected by the statement | |
shared_blks_hit | int8 | Total number of shared block cache hits by the statement | |
shared_blks_read | int8 | Total number of shared blocks read by the statement | |
shared_blks_dirtied | int8 | Total number of shared blocks dirtied by the statement | |
shared_blks_written | int8 | Total number of shared blocks written by the statement | |
local_blks_hit | int8 | Total number of local block cache hits by the statement | |
local_blks_read | int8 | Total number of local blocks read by the statement | |
local_blks_dirtied | int8 | Total number of local blocks dirtied by the statement | |
local_blks_written | int8 | Total number of local blocks written by the statement | |
temp_blks_read | int8 | Total number of temp blocks read by the statement | |
temp_blks_written | int8 | Total number of temp blocks written by the statement | |
shared_blk_read_time | float8 | Total time the statement spent reading shared blocks, in milliseconds (if track_io_timing is enabled, otherwise zero) | |
shared_blk_write_time | float8 | Total time the statement spent writing shared blocks, in milliseconds (if track_io_timing is enabled, otherwise zero) | |
local_blk_read_time | float8 | Total time the statement spent reading local blocks, in milliseconds (if track_io_timing is enabled, otherwise zero). In Postgres Pro versions lower than 17, contains zero. | |
local_blk_write_time | float8 | Total time the statement spent writing local blocks, in milliseconds (if track_io_timing is enabled, otherwise zero). In Postgres Pro versions lower than 17, contains zero. | |
temp_blk_read_time | float8 | Total time the statement spent reading temp blocks, in milliseconds (if track_io_timing is enabled, otherwise zero). In Postgres Pro versions lower than 15, contains zero. | |
temp_blk_write_time | float8 | Total time the statement spent writing temp blocks, in milliseconds (if track_io_timing is enabled, otherwise zero). In Postgres Pro versions lower than 15, contains zero. | |
wal_records | int8 | Total number of WAL records generated by the statement | |
wal_fpi | int8 | Total number of WAL full page images generated by the statement | |
wal_bytes | numeric | Total amount of WAL bytes generated by the statement | |
wal_buffers_full | bigint | Number of times the WAL buffers became full. In Postgres Pro versions lower than 18, contains zero. | |
jit_functions | int8 | Total number of functions JIT-compiled by the statement. In Postgres Pro versions lower than 15, contains zero. | |
jit_generation_time | float8 | Total time spent by the statement on generating JIT code, in milliseconds. In Postgres Pro versions lower than 15, contains zero. | |
jit_inlining_count | int8 | Number of times functions used in the statement have been inlined. In Postgres Pro versions lower than 15, contains zero. | |
jit_inlining_time | float8 | Total time spent by the statement on inlining functions, in milliseconds. In Postgres Pro versions lower than 15, contains zero. | |
jit_optimization_count | int8 | Number of times the statement has been optimized. In Postgres Pro versions lower than 15, contains zero. | |
jit_optimization_time | float8 | Total time spent by the statement on optimizing, in milliseconds. In Postgres Pro versions lower than 15, contains zero. | |
jit_emission_count | int8 | Number of times code has been emitted by the statement. In Postgres Pro versions lower than 15, contains zero. | |
jit_emission_time | float8 | Total time spent by the statement on emitting code, in milliseconds. In Postgres Pro versions lower than 15, contains zero. | |
jit_deform_count | int8 | Total number of tuple deform functions JIT-compiled by the statement. In Postgres Pro versions lower than 17, contains zero. | |
jit_deform_time | float8 | Total time spent by the statement on JIT-compiling tuple deform functions, in milliseconds. In Postgres Pro versions lower than 17, contains zero. | |
parallel_workers_to_launch | bigint | Number of parallel workers planned to be launched. In Postgres Pro versions lower than 18, contains zero. | |
parallel_workers_launched | bigint | Number of parallel workers actually launched. In Postgres Pro versions lower than 18, contains zero. | |
wait_stats | jsonb | A jsonb object containing statistics on wait events, for each execution of the query that uses the corresponding plan. Each statistic is provided in milliseconds and is a multiple of the pgpro_stats.profile_period configuration parameter. | |
inval_msgs | pgpro_stats_inval_msgs | Number of cache invalidation messages by type generated by the statement (if this is supported by the server, otherwise zero). | |
stats_since | timestamp with time zone | Time at which statistics gathering started for this statement | |
minmax_stats_since | timestamp with time zone | Time at which min/max statistics gathering started for this statement (fields min_plan_time, max_plan_time, min_exec_time and max_exec_time) |
Take into account that like pg_stat_statements, pgpro_stats normalizes into one record those DML queries (containing SELECT, INSERT, UPDATE, DELETE and MERGE commands) that have equivalent structures according to some internal hash value. Being compared this way, two queries are normally considered equal if they are semantically equivalent up to constants included in the queries. When the value of a constant in a query is ignored for comparison with other queries, this constant is replaced in the pgpro_stats output with a symbol of a parameter, such as, $k, where k is a positive integer. If a query already contains parameters, the initial value of k equals the number following the last number of a $n parameter in the original query text. If there are no parameters, the initial value of k equals 1. Note that sometimes hidden parameter symbols affect this numbering. For example, PL/pgSQL uses such hidden symbols to insert values of function local variables into queries, so a PL/pgSQL statement SELECT i + 1 INTO j will be represented as SELECT i + $2 in the normalized query text.
In some cases, queries with visibly different texts might get merged into a single pgpro_stats_statements entry; as explained above, this is expected to happen for semantically equivalent queries. In addition, if the only difference between queries is the number of elements in a list of constants, the list will get squashed down to a single element but shown with a commented-out list indicator:
=# SELECT pgpro_stats_statements_reset(); =# SELECT * FROM test WHERE a IN (1, 2, 3, 4, 5, 6, 7); =# SELECT * FROM test WHERE a IN (1, 2, 3, 4, 5, 6, 7, 8); =# SELECT query, calls FROM pgpro_stats_statements WHERE query LIKE 'SELECT%'; -[ RECORD 1 ]------------------------------ query | SELECT * FROM test WHERE a IN ($1 /*, ... */) calls | 2
In addition to these cases, there is a small chance of hash collisions causing unrelated queries to be merged into one entry. (This cannot happen for queries belonging to different users or databases, however.)
pgpro_stats uses a similar technique to normalize plan texts. When doing so, an attempt is made to associate numbers of constants in the plan text with the corresponding numbers of constants in the query text. If such an attempt appears unsuccessful for a certain constant in the plan text, it is assigned the number following the maximum number of a constant replaced in the query text. For example, consider the query:
SELECT 1::int, 'abc'::VARCHAR(3), 2::int;
pgpro_stats will replace numbers of constants in the query text and in the text of the corresponding plan as follows:
postgres=# SELECT query, plan FROM pgpro_stats_statements;
query | plan
------------------------------------------------+--------------------------------------------------
SELECT $1::int, $2::VARCHAR(3), $3::int | Result +
| Output: $1, $4, $3 +
In this plan text, it appeared possible to associate constants numbered 1 and 3 from the query text, but not the constant numbered 2, and the latter was replaced with the number following the maximum number in the query text, that is, number 4.
Replacement of numbers in plan texts has an exception for version numbers of XML documents. If in the original query such a number is represented with a constant, e.g., '1.0', it is retained as is in the plan text rather than replaced with $k. If the version number of an XML document is represented with an expression, replacement of constants follows usual rules.
In pgpro_stats, queries that have the same text hash values and the same plan hash values are merged into one pgpro_stats_statements entry. After replacing constants in plan texts, the rest of the plan will correspond to the plan text of the first among the merged queries included in the statistics. However, texts of other plans with this hash may differ not only in the constants replaced. Consider the following example.
Example G.1. Plan Executed with Partition Pruning
Consider the prepared query:
PREPARE test_stmt(bigint, bigint, bigint) AS SELECT * FROM ptest WHERE category_id IN ($1,$2,$3);
It queries the ptest table that is partitioned by the category_id column.
To further choose a generic plan, let's set the configuration parameter as follows:
SET plan_cache_mode TO force_generic_plan;
Let this query be called with different values:
EXECUTE test_stmt(1,2,3); EXECUTE test_stmt(2,3,4);
These queries will be merged in pgpro_stats, and the following plan text will be displayed:
Append
Subplans Removed: 17
-> Seq Scan on public.ptest_1
Output: ptest_1.id, ptest_1.category_id
Filter: (ptest_1.category_id = ANY (ARRAY[$1, $2, $3]))
-> Seq Scan on public.ptest_2
Output: ptest_2.id, ptest_2.category_id
Filter: (ptest_2.category_id = ANY (ARRAY[$1, $2, $3]))
-> Seq Scan on public.ptest_3
Output: ptest_3.id, ptest_3.category_id
Filter: (ptest_3.category_id = ANY (ARRAY[$1, $2, $3]))
Constants in ANY (ARRAY[$1, $2, $3]) were replaced, but partition table names ptest_1, ptest_2, ptest_3 correspond to the first saved plan, although the second query plan included scan of other partitions (ptest_2, ptest_3, ptest_4). These plans are considered equivalent because the plan hash is computed from the initial generic plan, which includes subplans with scans of all partitions. But pgpro_stats only saves the text of the plan that was actually executed, with partition pruning during the execution. Therefore, the plan text only includes the partitions that were scanned (in the first query saved). Subplans Removed: 17 shows that scans for other partitions were removed during the partition pruning.
G.4.4.2. The pgpro_stats_totals View #
The aggregate statistics gathered by the module are made available via a view named pgpro_stats_totals. This view contains one row for each distinct object (up to the maximum number of distinct objects that the module can track). The columns of the view are shown in Table G.76.
Table G.76. pgpro_stats_totals Columns
| Name | Type | Description |
|---|---|---|
object_type | text | Type of the object for which aggregated statistics are collected: "cluster", "database", "user", "client_addr", "application", "backend", "session" |
object_id | bigint | ID of the object: OID for databases and users, PID for backends, NULL for others |
object_name | text | Textual name of the object or NULL |
queries_planned | int8 | Number of queries planned |
total_plan_time | float8 | Total time spent in the planning of statements, in milliseconds |
total_plan_rusage | pgpro_stats_rusage | Aggregate resource usage statistics of the statement planning |
queries_executed | int8 | Number of queries executed |
total_exec_time | float8 | Total time spent in the execution of statements, in milliseconds |
total_exec_rusage | pgpro_stats_rusage | Aggregate resource usage statistics of the statement execution |
rows | int8 | Total number of rows retrieved or affected by the statements |
shared_blks_hit | int8 | Total number of shared block cache hits by the statements |
shared_blks_read | int8 | Total number of shared blocks read by the statements |
shared_blks_dirtied | int8 | Total number of shared blocks dirtied by the statements |
shared_blks_written | int8 | Total number of shared blocks written by the statements |
local_blks_hit | int8 | Total number of local block cache hits by the statements |
local_blks_read | int8 | Total number of local blocks read by the statements |
local_blks_dirtied | int8 | Total number of local blocks dirtied by the statements |
local_blks_written | int8 | Total number of local blocks written by the statements |
temp_blks_read | int8 | Total number of temp blocks read by the statements |
temp_blks_written | int8 | Total number of temp blocks written by the statements |
shared_blk_read_time | float8 | Total time the statements spent reading shared blocks, in milliseconds (if track_io_timing is enabled, otherwise zero) |
shared_blk_write_time | float8 | Total time the statements spent writing shared blocks, in milliseconds (if track_io_timing is enabled, otherwise zero) |
local_blk_read_time | float8 | Total time the statements spent reading local blocks, in milliseconds (if track_io_timing is enabled, otherwise zero). In Postgres Pro versions lower than 17, contains zero. |
local_blk_write_time | float8 | Total time the statements spent writing local blocks, in milliseconds (if track_io_timing is enabled, otherwise zero). In Postgres Pro versions lower than 17, contains zero. |
temp_blk_read_time | float8 | Total time the statements spent reading temp blocks, in milliseconds (if track_io_timing is enabled, otherwise zero). In Postgres Pro versions lower than 15, contains zero. |
temp_blk_write_time | float8 | Total time the statements spent writing temp blocks, in milliseconds (if track_io_timing is enabled, otherwise zero). In Postgres Pro versions lower than 15, contains zero. |
wal_records | int8 | Total number of WAL records generated by the statements |
wal_fpi | int8 | Total number of WAL full page images generated by the statements |
wal_bytes | numeric | Total amount of WAL bytes generated by the statements |
wal_buffers_full | bigint | Total number of times the WAL buffers became full. In Postgres Pro versions lower than 18, contains zero. |
jit_functions | int8 | Total number of functions JIT-compiled by the statements. In Postgres Pro versions lower than 15, contains zero. |
jit_generation_time | float8 | Total time spent by the statements on generating JIT code, in milliseconds. In Postgres Pro versions lower than 15, contains zero. |
jit_inlining_count | int8 | Number of times functions used in the statements have been inlined. In Postgres Pro versions lower than 15, contains zero. |
jit_inlining_time | float8 | Total time spent by the statements on inlining functions, in milliseconds. In Postgres Pro versions lower than 15, contains zero. |
jit_optimization_count | int8 | Number of times the statements have been optimized. In Postgres Pro versions lower than 15, contains zero. |
jit_optimization_time | float8 | Total time spent by the statements on optimizing, in milliseconds. In Postgres Pro versions lower than 15, contains zero. |
jit_emission_count | int8 | Number of times code has been emitted by the statements. In Postgres Pro versions lower than 15, contains zero. |
jit_emission_time | float8 | Total time spent by the statements on emitting code, in milliseconds. In Postgres Pro versions lower than 15, contains zero. |
jit_deform_count | int8 | Total number of tuple deform functions JIT-compiled by the statements. In Postgres Pro versions lower than 17, contains zero. |
jit_deform_time | float8 | Total time spent by the statements on JIT-compiling tuple deform functions, in milliseconds. In Postgres Pro versions lower than 17, contains zero. |
parallel_workers_to_launch | bigint | Number of parallel workers planned to be launched by the statements. In Postgres Pro versions lower than 18, contains zero. |
parallel_workers_launched | bigint | Number of parallel workers actually launched by the statements. In Postgres Pro versions lower than 18, contains zero. |
wait_stats | jsonb | A jsonb object containing statistics on wait events for each execution of the queries. Each statistic is provided in milliseconds and is a multiple of the pgpro_stats.profile_period configuration parameter. |
inval_msgs | pgpro_stats_inval_msgs | Number of cache invalidation messages by type generated by the statements (if this is supported by the server, otherwise zero). |
cache_resets | int4 | Number of shared cache resets (only for cluster, databases and backends). Gets incremented for a backend when it receives a full cache reset message. |
stats_since | timestamp with time zone | Time at which statistics gathering started for the statements |
G.4.4.3. The pgpro_stats_info View #
The statistics of the pgpro_stats module itself are tracked and made available via a view named pgpro_stats_info. This view contains only a single row. The columns of the view are shown in Table G.77.
Table G.77. pgpro_stats_info Columns
| Name | Type | Description |
|---|---|---|
dealloc | bigint | Total number of times pgpro_stats_statements entries about the least-executed statements were deallocated because more distinct statements than pgpro_stats.max were observed |
stats_reset | timestamp with time zone | Time at which all statistics in the pgpro_stats_statements view were last reset |
G.4.4.4. The pgpro_stats_metrics View #
The metrics gathered by pgpro_stats are displayed in the pgpro_stats_metrics view. The table below describes the columns of the view.
Table G.78. pgpro_stats_metrics Columns
| Name | Type | Description |
|---|---|---|
metric_number | int4 | A unique ID of the collected metric assigned by user. This ID is included into parameter names that define the metric. |
metric_name | text | The name of the metric defined by the pgpro_stats.metric_ parameter |
db_name | text | The name of the database for which a particular metric was collected |
ts | timestamptz | The time when the metric value got calculated |
value | jsonb | The result of the query used for metric measurement. It is serialized in jsonb as an array of objects received via to_jsonb(. If an error occurs, a single object is returned that contains code, message, detail, and hint fields. |
G.4.4.5. The pgpro_stats_archiver View #
The pgpro_stats_archiver view will contain one row showing data about the archiver process of the cluster.
Table G.79. pgpro_stats_archiver Columns
| Column | Type | Description |
|---|---|---|
archived_count | bigint | Number of WAL files that have been successfully archived |
last_archived_wal | text | Name of the last WAL file successfully archived |
last_archived_time | timestamp with time zone | Time of the last successful archive operation |
failed_count | bigint | Number of failed attempts for archiving WAL files |
last_failed_wal | text | Name of the WAL file of the last failed archival operation |
last_failed_time | timestamp with time zone | Time of the last failed archival operation |
active_time | int8 | Overall time that the archiver process was active |
archive_command_time | int8 | Overall execution time of the archive command |
stats_reset | timestamp with time zone | Time at which these statistics were last reset |
G.4.4.6. The pgpro_stats_vacuum_database View #
Important
Starting with Postgres Pro 16, this view contains no data because the statistics to be displayed are available through the catalog view pg_stats_vacuum_database (see System Views for details).
The pgpro_stats_vacuum_database view will contain one row for each database in the current cluster, showing statistics about vacuuming that database. These statistics are collected by the core system as explained in Section 27.2. The table below describes the columns of the view.
Table G.80. pgpro_stats_vacuum_database Columns
| Column | Type | Description |
|---|---|---|
dbid | oid | OID of a database |
total_blks_read | int8 | Number of database blocks read by vacuum operations performed on this database |
total_blks_hit | int8 | Number of times database blocks were found in the buffer cache by vacuum operations performed on this database |
total_blks_dirtied | int8 | Number of database blocks dirtied by vacuum operations performed on this database |
total_blks_written | int8 | Number of database blocks written by vacuum operations performed on this database |
wal_records | int8 | Total number of WAL records generated by vacuum operations performed on this database |
wal_fpi | int8 | Total number of WAL full page images generated by vacuum operations performed on this database |
wal_bytes | numeric | Total amount of WAL bytes generated by vacuum operations performed on this database |
blk_read_time | float8 | Time spent reading database blocks by vacuum operations performed on this database, in milliseconds (if track_io_timing is enabled, otherwise zero) |
blk_write_time | float8 | Time spent writing database blocks by vacuum operations performed on this database, in milliseconds (if track_io_timing is enabled, otherwise zero) |
delay_time | float8 | Time spent sleeping in a vacuum delay point by vacuum operations performed on this database, in milliseconds (see Section 18.10.2 for details) |
system_time | float8 | System CPU time of vacuuming this database, in milliseconds |
user_time | float8 | User CPU time of vacuuming this database, in milliseconds |
total_time | float8 | Total time of vacuuming this database, in milliseconds |
interrupts | int4 | Number of times vacuum operations performed on this database were interrupted on any errors |
G.4.4.7. The pgpro_stats_vacuum_tables View #
Important
Starting with Postgres Pro 16, this view contains no data because the statistics to be displayed are available through the catalog view pg_stats_vacuum_tables (see System Views for details).
The pgpro_stats_vacuum_tables view will contain one row for each table in the current database (including TOAST tables), showing statistics about vacuuming that specific table. These statistics are collected by the core system as explained in Section 27.2. The table below describes the columns of the view.
Table G.81. pgpro_stats_vacuum_tables Columns
| Column | Type | Description |
|---|---|---|
relid | oid | OID of a table |
schema | name | Name of the schema this table is in |
relname | name | Name of this table |
total_blks_read | int8 | Number of database blocks read by vacuum operations performed on this table |
total_blks_hit | int8 | Number of times database blocks were found in the buffer cache by vacuum operations performed on this table |
total_blks_dirtied | int8 | Number of database blocks dirtied by vacuum operations performed on this table |
total_blks_written | int8 | Number of database blocks written by vacuum operations performed on this table |
rel_blks_read | int8 | Number of blocks vacuum operations read from this table |
rel_blks_hit | int8 | Number of times blocks of this table were already found in the buffer cache by vacuum operations, so that a read was not necessary (this only includes hits in the Postgres Pro buffer cache, not the operating system's file system cache) |
pages_scanned | int8 | Number of pages examined by vacuum operations performed on this table |
pages_removed | int8 | Number of pages removed from the physical storage by vacuum operations performed on this table |
pages_frozen | int8 | Number of times vacuum operations marked pages of this table as all-frozen in the visibility map |
pages_all_visible | int8 | Number of times vacuum operations marked pages of this table as all-visible in the visibility map |
tuples_deleted | int8 | Number of dead tuples vacuum operations deleted from this table |
tuples_frozen | int8 | Number of tuples of this table that vacuum operations marked as frozen |
dead_tuples | int8 | Number of dead tuples vacuum operations left in this table due to their visibility in transactions |
index_vacuum_count | int8 | Number of times indexes on this table were vacuumed |
rev_all_frozen_pages | int8 | Number of times the all-frozen mark in the visibility map was removed for pages of this table |
rev_all_visible_pages | int8 | Number of times the all-visible mark in the visibility map was removed for pages of this table |
wal_records | int8 | Total number of WAL records generated by vacuum operations performed on this table |
wal_fpi | int8 | Total number of WAL full page images generated by vacuum operations performed on this table |
wal_bytes | numeric | Total amount of WAL bytes generated by vacuum operations performed on this table |
blk_read_time | float8 | Time spent reading database blocks by vacuum operations performed on this table, in milliseconds (if track_io_timing is enabled, otherwise zero) |
blk_write_time | float8 | Time spent writing database blocks by vacuum operations performed on this table, in milliseconds (if track_io_timing is enabled, otherwise zero) |
delay_time | float8 | Time spent sleeping in a vacuum delay point by vacuum operations performed on this table, in milliseconds (see Section 18.10.2 for details) |
system_time | float8 | System CPU time of vacuuming this table, in milliseconds |
user_time | float8 | User CPU time of vacuuming this table, in milliseconds |
total_time | float8 | Total time of vacuuming this table, in milliseconds |
interrupts | integer | Number of times vacuum operations performed on this table were interrupted on any errors |
Columns total_*, wal_* and blk_* include data on vacuuming indexes on this table, while columns system_time and user_time only include data on vacuuming the heap.
G.4.4.8. The pgpro_stats_vacuum_indexes View #
Important
Starting with Postgres Pro 16, this view contains no data because the statistics to be displayed are available through the catalog view pg_stats_vacuum_indexes (see System Views for details).
The pgpro_stats_vacuum_indexes view will contain one row for each index in the current database (including TOAST table indexes), showing statistics about vacuuming that specific index. These statistics are collected by the core system as explained in Section 27.2. The table below describes the columns of the view.
Table G.82. pgpro_stats_vacuum_indexes Columns
| Column | Type | Description |
|---|---|---|
relid | oid | OID of an index |
schema | name | Name of the schema this index is in |
relname | name | Name of this index |
total_blks_read | int8 | Number of database blocks read by vacuum operations performed on this index |
total_blks_hit | int8 | Number of times database blocks were found in the buffer cache by vacuum operations performed on this index |
total_blks_dirtied | int8 | Number of database blocks dirtied by vacuum operations performed on this index |
total_blks_written | int8 | Number of database blocks written by vacuum operations performed on this index |
rel_blks_read | int8 | Number of blocks vacuum operations read from this index |
rel_blks_hit | int8 | Number of times blocks of this index were already found in the buffer cache by vacuum operations, so that a read was not necessary (this only includes hits in the Postgres Pro buffer cache, not the operating system's file system cache) |
pages_deleted | int8 | Number of pages deleted by vacuum operations performed on this index |
tuples_deleted | int8 | Number of dead tuples vacuum operations deleted from this index |
wal_records | int8 | Total number of WAL records generated by vacuum operations performed on this index |
wal_fpi | int8 | Total number of WAL full page images generated by vacuum operations performed on this index |
wal_bytes | numeric | Total amount of WAL bytes generated by vacuum operations performed on this index |
blk_read_time | float8 | Time spent reading database blocks by vacuum operations performed on this index, in milliseconds (if track_io_timing is enabled, otherwise zero) |
blk_write_time | float8 | Time spent writing database blocks by vacuum operations performed on this index, in milliseconds (if track_io_timing is enabled, otherwise zero) |
delay_time | float8 | Time spent sleeping in a vacuum delay point by vacuum operations performed on this index, in milliseconds (see Section 18.10.2 for details) |
system_time | float8 | System CPU time of vacuuming this index, in milliseconds |
user_time | float8 | User CPU time of vacuuming this index, in milliseconds |
total_time | float8 | Total time of vacuuming this index, in milliseconds |
interrupts | integer | Number of times vacuum operations performed on this index were interrupted on any errors |
G.4.4.9. The pgpro_stats_relcaches View #
The pgpro_stats_relcaches view is available if pgpro_stats.track_relcaches is true for Postgres Pro versions 17 or higher. This view will contain one row for each database in the cluster, showing statistics about creations and removals of the relation cache initialization file pg_internal.init. Creations and removals that occur after the server restart are only included in the statistics. The number of rows in this view is controlled by the pgpro_stats.max_relcaches configuration parameter. The table below describes the columns of the view.
Table G.83. pgpro_stats_relcaches Columns
| Column | Type | Description |
|---|---|---|
dboid | oid | OID of the database. dboid = 0 corresponds to pg_internal.init for common cluster files irrelated to any database. |
total_creations | int | Number of attempts to create the pg_internal.init file for this database (or for common cluster files if dboid = 0) since the statistics in this view were last reset |
successful_creations | int | Number of times the pg_internal.init file was successfully created for this database (or for common cluster files if dboid = 0) since the statistics in this view were last reset |
removals | int | Number of times the pg_internal.init file was removed for this database (or for common cluster files if dboid = 0) since the statistics in this view were last reset. Note that removals that occur at server restarts during postmaster startup are not included in the statistics. |
stats_since | timestamp | Time at which these statistics were last reset |
Note
As this view displays the metrics collected since the statistics were last reset, successful_creations can appear smaller than removals.
G.4.5. Data Types #
G.4.5.1. The pgpro_stats_rusage Type #
pgpro_stats_rusage is a record type that contains resource usage statistics of statement planning/execution. The fields of this type are shown in Table G.84.
Table G.84. pgpro_stats_rusage Fields
| Name | Type | Description |
|---|---|---|
reads | bigint | Number of bytes read by the filesystem layer |
writes | bigint | Number of bytes written by the filesystem layer |
user_time | double precision | User CPU time used |
system_time | double precision | System CPU time used |
minflts | bigint | Number of page reclaims (soft page faults) |
majflts | bigint | Number of page faults (hard page faults) |
nswaps | bigint | Number of swaps |
msgsnds | bigint | Number of IPC messages sent |
msgrcvs | bigint | Number of IPC messages received |
nsignals | bigint | Number of signals received |
nvcsws | bigint | Number of voluntary context switches |
nivcsws | bigint | Number of involuntary context switches |
G.4.6. Functions #
-
pgpro_stats_statements_reset(userid Oid, dbid Oid, queryid bigint, planid bigint, minmax_only boolean) returns timestamp with time zone pgpro_stats_statements_resetdiscards statistics gathered so far bypgpro_statscorresponding to the specifieduserid,dbid,queryid, andplanid. If any of the parameters are not specified, the default value0(invalid) is used for each of them and the statistics that match with other parameters will be reset. If no parameter is specified or all the specified parameters are0(invalid), it will discard all statistics. If all statistics in thepgpro_stats_statementsview are discarded, it will also reset the statistics in thepgpro_stats_infoview. Whenminmax_onlyistrueonly the values of minimum and maximum planning and execution time will be reset (i.e.min_plan_time,max_plan_time,min_exec_timeandmax_exec_timefields). The default value forminmax_onlyparameter isfalse. Time of last min/max reset performed is shown inminmax_stats_sincefield of thepgpro_stats_statementsview. This function returns the time of a reset. This time is saved tostats_resetfield ofpgpro_stats_infoview or tominmax_stats_sincefield of thepgpro_stats_statementsview if the corresponding reset was actually performed. By default, this function can only be executed by superusers. Access may be granted to others usingGRANT.Note
As statistics in the
pgpro_stats_vacuum_database,pgpro_stats_vacuum_tables, andpgpro_stats_vacuum_indexesviews are collected by the core system, to reset them, call thepg_stat_reset()function (see Section 27.2.26 for details).-
pgpro_stats_statements(showtext boolean) returns setof record The
pgpro_stats_statementsview is defined in terms of a function also namedpgpro_stats_statements. Users can also call thepgpro_stats_statementsfunction directly, and by specifyingshowtext := falsemake query text be omitted (that is, theOUTargument that corresponds to the view'squerycolumn will return nulls). This feature is intended to support external tools that might wish to avoid the overhead of repeatedly retrieving query texts of indeterminate length. Such tools can instead cache the first query text observed for each entry themselves, since that is allpgpro_statsitself does, and then retrieve query texts only as needed. Since the server stores query texts in a file, this approach may reduce physical I/O for repeated examination of thepgpro_stats_statementsdata.-
pgpro_stats_statements_filtered(showtext boolean, userid oid, dboid oid, queryid bigint, planid bigint) returns setof record The
pgpro_stats_statements_filteredfunction allows you to filter statistics similar to those provided in thepgpro_stats_statementsview by one or several fields specified by the parametersuserid,dbid,queryid, andplanid. If any of these parameters are not specified, the default value0(invalid) is used for each of them and the statistics that match with other parameters will be returned.showtextistrueby default. Specifyingshowtext := falsemakes query text be omitted, as explained for thepgpro_stats_statementsfunction. Becausepgpro_stats_statements_filteredonly selects the needed rows, it returns the statistics faster than a query like this:SELECT * FROM pgpro_stats_statements WHERE userid = ? AND dbid = ? AND queryid = ? AND planid = ?;
-
pgpro_stats_info() returns record pgpro_stats_infoview is defined in terms of a function also namedpgpro_stats_info. Users can also call thepgpro_stats_infofunction directly.-
pgpro_stats_totals_reset(type text, id bigint) returns timestamp with timezone pgpro_stats_totals_resetdiscards statistics gathered so far bypgpro_statscorresponding to the specified objecttypeandid. If no parameter is specified or thetypeparameter is set to0, all statistics will be discarded. Iftypeis set to a valid object type, then ifidis specified, then statistics will be discarded only for the specified object, else, statistics will be discarded for all objects of the specified type. Otherwise, no statistics will be discarded. This function returns the time of a reset. By default, this function can only be executed by superusers. Access may be granted to others usingGRANT.-
pgpro_stats_totals() returns setof record The
pgpro_stats_totalsview is defined in terms of a function also namedpgpro_stats_totals. Users can also call thepgpro_stats_totalsfunction directly.-
pgpro_stats_metrics() returns setof record Defines the
pgpro_stats_metricsview, which is described in detail in Table G.78.-
pgpro_stats_get_archiver() returns setof record Defines the
pgpro_stats_archiverview, which is described in detail in Table G.79.-
pgpro_stats_wal_sender_crc_errors() returns bigint In Postgres Pro Enterprise, returns the number of errors detected by the WAL sender process when the
wal_sender_check_crcparameter ison. In Postgres Pro Standard, returns zero. Note that this counter is reset to zero when the cluster restarts.-
pgpro_stats_vacuum_database(dboid oid) returns setof record Defines the row of the
pgpro_stats_vacuum_databaseview, which is described in detail in Table G.80, for the database specified bydboid.-
pgpro_stats_vacuum_tables(dboid oid, relid oid) returns setof record Defines the row of the
pgpro_stats_vacuum_tablesview, which is described in detail in Table G.81, for the database specified bydboidand table specified byreloid. Ifreloid= 0, the statistics for each table in the specified database are returned.-
pgpro_stats_vacuum_indexes(dboid oid, relid oid) returns setof record Defines the row of the
pgpro_stats_vacuum_indexesview, which is described in detail in Table G.82, for the database specified bydboidand index specified byreloid. Ifreloid= 0, the statistics for each index in the specified database are returned.-
pgpro_stats_relcaches(dboid Oid, total_creations int, successful_creations int, removals int, stats_since timestamp) returns setof record pgpro_stats_relcachescan only be called in Postgres Pro versions 17 or higher. It defines the row of thepgpro_stats_relcachesview, which is described in detail in Table G.83, for the database specified bydboid. Ifdboid= 0, the row corresponding topg_internal.initfor common cluster files is returned.-
pgpro_stats_relcaches_reset([dboid oid]) returns timestamp with time zone pgpro_stats_relcaches_resetcan only be called in Postgres Pro versions 17 or higher. It discards the statistics that are returned by thepgpro_stats_relcachesview. Ifdboid> 0 is passed, the statistics corresponding to the specified database are reset. Ifdboid= 0 is passed, the statistics corresponding topg_internal.initfor common cluster files are reset. Without thedboidparameter, all the statistics are reset. Returns the date and time of resetting.
G.4.6.1. Functions for Creating Views that Emulate Other Extensions #
pgpro_stats can create views similar to those available in pg_stat_statements and pg_stat_kcache extensions. Specifically, pg_stat_statements, pg_stat_statements_info, pg_stat_kcache and pg_stat_kcache_detail views can be created. Each view is only created in a Postgres Pro version if it is available in pg_stat_statements/pg_stat_kcache extension for the same version of Postgres Pro/PostgreSQL. For example, the pg_stat_statements_info view is only created in Postgres Pro versions starting with 14. The following functions enable creating these views:
By default, these functions can only be executed by superusers. Access may be granted to others using GRANT.
To create pg_stat_statements* views, drop the pg_stat_statements extension if it was previously installed and call the function:
select pgpro_stats_create_pg_stat_statements_compatible_views();
To create pg_stat_kcache* views, drop the pg_stat_kcache extension if it was previously installed and call the function:
select pgpro_stats_create_pg_stat_kcache_compatible_views();
Once the views are created, you can work with them as if the pg_stat_statements/pg_stat_kcache extension is installed.
If you need to remove the views created earlier, do it in a regular way:
drop view pg_stat_statements; drop view pg_stat_statements_info; drop view pg_stat_kcache; drop view pg_stat_kcache_detail;
G.4.7. Configuration Parameters #
G.4.7.1. General Settings #
-
pgpro_stats.max(integer) # pgpro_stats only collects statistics about most frequent queries. The less frequently a query appears during the server opertaion, the less probable its inclusion in the statistics. Rare queries are almost immediately evicted from the statistics by more frequent queries. The
pgpro_stats.maxparameter defines the maximum number of unique pairs (normalized query text, normalized plan text) tracked by the module, (i.e., the maximum number of rows in thepgpro_stats_statementsview). The larger this value, the larger the number of queries for which the information is stored. But this is achieved at the cost of reduced server performance when waiting for locks trying to access the statistics table in the shared memory and when periodically collecting garbage in the file with texts of queries and plans. The default value is 5000. This parameter can only be set at server start.-
pgpro_stats.max_totals(integer) # pgpro_stats.max_totalsis the maximum number of objects tracked by the module (i.e., the maximum number of rows in thepgpro_stats_totalsview). If more distinct objects than that are observed, information about least-used objects is discarded. The default value is 1000. This parameter can only be set at server start.-
pgpro_stats.track(enum) # pgpro_stats.trackcontrols which statements are counted by the module. Specifytopto track top-level statements (those issued directly by clients),allto also track nested statements (such as statements invoked within functions) with nesting level not greater than 100, ornoneto disable statement statistics collection. The default value istop. Only superusers can change this setting.-
pgpro_stats.track_utility(boolean) # pgpro_stats.track_utilitycontrols whether utility commands are tracked by the module. Utility commands are all those other thanSELECT,INSERT,UPDATEandDELETE. The default value ison. Only superusers can change this setting.-
pgpro_stats.track_planning(boolean) # pgpro_stats.track_planningcontrols whether planning operations and duration are tracked by the module. Enabling this parameter may incur a noticeable performance penalty, especially when statements with identical query structure are executed by many concurrent connections which compete to update a small number ofpgpro_stats_statementsentries. The default value isoff. Only superusers can change this setting.-
pgpro_stats.track_totals(boolean) # pgpro_stats.track_totalscontrols whether aggregate statistics for objects (cluster, users, databases etc.) are tracked by the module. The default value ison. Only superusers can change this setting.-
pgpro_stats.track_cluster(boolean) # pgpro_stats.track_clustercontrols whether aggregate statistics for the cluster are tracked by the module if pgpro_stats.track_totals is on. The default value ison. Only superusers can change this setting.-
pgpro_stats.track_databases(boolean) # pgpro_stats.track_databasescontrols whether aggregate statistics for the databases are tracked by the module if pgpro_stats.track_totals is on. The default value ison. Only superusers can change this setting.-
pgpro_stats.track_users(boolean) # pgpro_stats.track_userscontrols whether aggregate statistics for the users are tracked by the module if pgpro_stats.track_totals is on. The default value ison. Only superusers can change this setting.-
pgpro_stats.track_applications(boolean) # pgpro_stats.track_applicationscontrols whether aggregate statistics for the applications (whose names are set by application_name) are tracked by the module if pgpro_stats.track_totals is on. The default value ison. Only superusers can change this setting.-
pgpro_stats.track_client_addr(boolean) # pgpro_stats.track_client_addrcontrols whether aggregate statistics for the client IP addresses are tracked by the module. The default value ison. Only superusers can change this setting.-
pgpro_stats.track_backends(boolean) # pgpro_stats.track_backendscontrols whether aggregate statistics for the backends are tracked by the module. The default value ison. Only superusers can change this setting.-
pgpro_stats.track_sessions(boolean) # pgpro_stats.track_sessionscontrols whether aggregate statistics for the sessions are tracked by the module.The aggregate statistics tracked for the sessions are displayed in the
pgpro_stats_totalsview with the session ID contained in theobject_namecolumn, as the session ID consists of two parts separated by dot, as explained in the description of the log_line_prefix configuration parameter.The default value is
on. Only superusers can change this setting.-
pgpro_stats.save(boolean) # pgpro_stats.savespecifies whether to save statement statistics across server shutdowns. If it isoffthen statistics are neither saved at shutdown nor reloaded at server start. The default value ison. This parameter can only be set in thepostgresql.conffile or on the server command line.-
pgpro_stats.plan_format(text) # pgpro_stats.plan_formatselects theEXPLAINformat for the query plan. Possible values aretext,xml,json, andyaml. The default value istext. Changing this parameter requires a server restart.-
pgpro_stats.enable_profile(boolean) # pgpro_stats.enable_profileenables sampling of wait events for separate statements. The default value istrue. Changing this parameter requires a server restart.-
pgpro_stats.query_sample_rate(float) # As pgpro_stats only collects statistics about most frequent queries, and rare queries are not included in the statistics, you can reduce the effect of the statistics collection on the server performance. This is possible because some time later than the statistics collection starts, almost all the statistics collected by the module will contain queries that are not very infrequent, and the set of types of the collected queries will not further change much if the value of pgpro_stats.max is sufficient and the average frequency for most of the frequent queries has no significant changes with the periods larger than the observation time. Such a stationary distribution of collected queries can also be achieved by increasing the time of the statistics collection, for example, twice, but only adding each second query to the statistics instead of every query, or considering each query, but adding queries to the statistics randomly, with a given probability. In this example, it equals 0.5. This allows you to considerably reduce the server load at the cost of increasing the time of the statistics collection.
pgpro_stats.query_sample_rateis the parameter to implement this approach. For example: ifpgpro_stats.query_sample_rateis set to 0.2 (1/5), in five hours of the server operation under the above conditions, the statistics will be collected that is similar to the statistics collected withpgpro_stats.query_sample_rate= 1 in an hour.You can set up
pgpro_stats.query_sample_rateby experiment. Choose the observation time depending on the environment of the server operation, for example: one hour. Look at the collected statistics an hour after the start and then an hour later without resetting the statistics. If the main difference appears to be in the increased number of collected queries (calls) rather than in the type of the queries, you can safely reducepgpro_stats.query_sample_ratetwice. In the case of a considerable difference in the types of the collected queries, increase the observtion time and/or thepgpro_stats.maxparameter.The default value is
1.0. Changing this parameter requires a server restart.-
pgpro_stats.profile_period(integer) # pgpro_stats.profile_periodspecifies the period, in milliseconds, during which to sample wait events. The default value is10. Only superusers can change this setting.-
pgpro_stats.metrics_buffer_size(integer) # pgpro_stats.metrics_buffer_sizespecifies the size of the ring buffer used for collecting statistical metrics. The default value is16kB. Changing this parameter requires a server restart.-
pgpro_stats.metrics_workers(integer) # pgpro_stats.metrics_workersspecifies the number of workers used to collect statistical metrics. If this parameter is set to 2 or higher, one of the workers serves as the primary worker distributing queries to other workers. If only one worker is available, it gets reloaded to connect to different databases. Setting this parameter to0disables metrics collection. The default value is2. Changing this parameter requires a server restart.-
pgpro_stats.stats_temp_directory(string) # pgpro_stats.stats_temp_directoryspecifies the directory with the external file to store query texts. This can be a path relative to the data directory or an absolute path. Changing this parameter requires a server restart.-
pgpro_stats.track_relcaches(boolean) # pgpro_stats.track_relcachesenables collecting statistics about creations and removals of the relation cache initialization filepg_internal.init, which is provided in thepgpro_stats_relcachesview. The default value isfalse. Enabling this parameter requires the server restart.-
pgpro_stats.max_relcaches(integer) # pgpro_stats.max_relcachesdefines the maximum number of rows in thepgpro_stats_relcachesview, that is, the number of databases tracked in the statistics about creations and removals ofpg_internal.initplus one (for the statistics onpg_internal.initfor common cluster files). When this size is exceeded, information about databases that was last updated before anything else is discarded.-
pgpro_stats.enable_warnings(boolean) # pgpro_stats.enable_warningsadds a warning to theplanfield of thepgpro_stats_statementsview if the plan was executed with partition pruning. The warning reads: “pgpro_stats warning: Some subplans could be pruned based on actual parameter values. This output reflects one possible execution plan.” The default value isfalse. If this parameter is enabled, the plan in Example G.1 will contain the warning.
G.4.7.2. Metrics Settings #
The following parameters can be used to define a custom metric to collect. The N placeholder in the parameter name serves as a unique identifier of the metric to which this setting should apply; it must be set to a non-negative integer for each metric.
When you add these parameters for a new metric, you have to restart the server for the changes to take effect.
-
pgpro_stats.metric_(N_nametext) The name of metric
N. This name will be displayed in themetric_namecolumn of thepgpro_stats_metricsview.-
pgpro_stats.metric_(N_querytext) The query statement that defines the metric to collect.
-
pgpro_stats.metric_(N_periodinteger) The time interval at which to collect metric
N, in milliseconds. Default: 60000 ms-
pgpro_stats.metric_(N_dbtext) The list of databases for which to collect metric
N. Database names must be separated by commas. You can specify the*character to select all databases in the cluster except the template databases. If you need to analyze the template databases as well, you have to specify them explicitly.-
pgpro_stats.metric_(N_usertext) The name of the user on behalf of which to collect metric
N. This user must have access to the database for which the metric is collected.
G.4.8. Tracing of Application Sessions #
In pgpro_stats, tracing of application sessions is implemented. It is based on filters, which trigger logging the execution of queries that match filtering conditions. Queries and their EXPLAIN output are logged in so-called trace files specified by the user or in the system log file (if the trace file is not specified). Filters are stored in a table located in the shared memory. The rows of this table represent filters, and the columns contain filtering conditions and EXPLAIN options to be used (see EXPLAIN for details). You should fill this table with filters to start tracing of queries.
Once a database administrator adds a filter in any session, all subsequent executions of queries that match the filter conditions will be traced by all sessions of the instance without a need in the server restart. In other words, filters can be added, deleted, or updated “on the fly”, and tracing with these filters immediately starts for existing and future sessions.
Note
Operations of adding, deleting, or updating filters are not transactional. Changes to the table of filters are not rolled back together with the transaction where these changes were made.
Columns of the table that stores filters are also called filter attributes. They are described in Table G.85.
Table G.85. Filter Attributes
| Name | Type | Description |
|---|---|---|
filter_id | integer | Unique filter ID, which is automatically assigned to a filter when it is created, numbered from 1. |
active | boolean | With the value of false, the filter is not active, which means that queries matching this filter are not logged. Default: true. |
alias | name | Filter name, which can be specified for convenience. Only shown in the output of the pgpro_stats_trace_show() function. Default: empty string. |
tracefile | name | Name of the trace file, where queries matching the filter and their EXPLAIN output are logged. If this filename if not specified, logging is done to the system log with the log level specified by pgpro_stats.trace_log_level. Trace files are created in directory and have trace extension. |
pid | integer | Process ID of the backend that executes the statement |
database_name | name | Name of the database where the statement is executed |
client_addr | name | IP address of the client connected to this backend |
application_name | name | Name of the application that invoked execution of the statement |
username | name | Name of the user who executes the statement |
queryid | bigint | Internal hash code, computed from the statement's parse tree |
planid | bigint | Internal hash code, computed from the statement's plan tree |
duration | float8 | Time spent in the planning and execution of the statement, in milliseconds |
plan_time | float8 | Time spent in the planning of the statement, in milliseconds |
exec_time | float8 | Time spent in the execution of the statement, in milliseconds |
user_time | float8 | User CPU time used in planning and execution of the statement |
system_time | float8 | System CPU time used in planning and execution of the statement |
rows | int8 | Total number of rows retrieved or affected by the statement |
shared_blks_hit | int8 | Total number of shared block cache hits by the statement |
shared_blks_read | int8 | Total number of shared blocks read by the statement |
shared_blks_fetched | int8 | Total number of shared blocks fetched from buffers by the statement |
shared_blks_dirtied | int8 | Total number of shared blocks dirtied by the statement |
shared_blks_written | int8 | Total number of shared blocks written by the statement |
local_blks_hit | int8 | Total number of local block cache hits by the statement |
local_blks_read | int8 | Total number of local blocks read by the statement |
local_blks_fetched | int8 | Total number of local blocks fetched from buffers by the statement |
local_blks_dirtied | int8 | Total number of local blocks dirtied by the statement |
local_blks_written | int8 | Total number of local blocks written by the statement |
temp_blks_read | int8 | Total number of temp blocks read by the statement |
temp_blks_written | int8 | Total number of temp blocks written by the statement |
wal_bytes | numeric | Total amount of WAL bytes generated by the statement |
total_wait_time | float8 | Total time execution of this statement spent waiting |
total_inval_msgs | bigint | Total number of cache invalidation messages generated by the statement (if this is supported by the server) |
explain_analyze | boolean | If true, the EXPLAIN output will be logged with the ANALYZE option. By default, defined by the pgpro_stats.explain_analyze_default configuration parameter. |
explain_verbose | boolean | If true, the EXPLAIN output will be logged with the VERBOSE option. By default, defined by the pgpro_stats.explain_verbose_default configuration parameter. |
explain_costs | boolean | If true, the EXPLAIN output will be logged with the COSTS option. By default, defined by the pgpro_stats.explain_costs_default configuration parameter. |
explain_settings | boolean | If true, the EXPLAIN output will be logged with the SETTINGS option. By default, defined by the pgpro_stats.explain_settings_default configuration parameter. |
explain_buffers | boolean | If true, the EXPLAIN output will be logged with the BUFFERS option. By default, defined by the pgpro_stats.explain_buffers_default configuration parameter. |
explain_wal | boolean | If true, the EXPLAIN output will be logged with the WAL option. By default, defined by the pgpro_stats.explain_wal_default configuration parameter. |
explain_timing | boolean | If true, the EXPLAIN output will be logged with the TIMING option. By default, defined by the pgpro_stats.explain_timing_default configuration parameter. |
explain_format | text | The value of the FORMAT option of EXPLAIN to be logged, which can be TEXT, XML, JSON, or YAML. By default, defined by the pgpro_stats.plan_format configuration parameter. |
time_info | boolean | If true, includes additional information in the session-tracing output in the format defined by explain_format: pid, duration in milliseconds, start time — start time of the query execution, and stop time — end time of the query execution. See Example G.3 for details. |
Filter attributes can be divided into the following groups:
Control attributes, from
filter_idtotracefilein Table G.85.Identification attributes, from
pidtoplanidin Table G.85.Threshold attributes, from
durationtototal_inval_msgsin Table G.85.Attributes that only control the output to the trace file or system log file and do not affect filtering. Most of them specify the
EXPLAINoptions. These are the attributes starting withexplain_analyzeup to the end of Table G.85.
Query execution will be traced if both of these conditions are met:
For all the specified identification attributes of the filter, the values of the respective characteristics of the query are the same as the values of these attributes.
For all the specified threshold attributes of the filter, the values of the respective characteristics of the query are greater than or equal to the limits specified in these attributes.
It is allowed not to assign values to attributes. For all the attributes except active, you can also explicitly assign the value of NULL. If the value of a control attribute is undefined or it was expclicitly set to NULL, this attribute will be assigned the default value shown in Table G.85. For identification and threshold attributes, undefined or NULL values mean that queries will not be filtered by the respective characteristic. If no values are defined for all identification and all threshold attributes, all the queries are taken to be matching this filter and will be logged. If the attributes specifying EXPLAIN options are undefined, the default values defined by the configuration parameters will be used (see Section G.4.8.2 for details).
Warning
Although when specifying a filter, you can assign values to any combination of filter attributes, bear in mind that a too general filter will lead to an excessive size of the trace file and will affect the performance more than desired as the main performance overhead is associated with writing to the trace file rather than with checking the filter conditions.
G.4.8.1. Session-Tracing Functions #
Specialized functions enable creation, update and deletion of query filters:
-
pgpro_stats_trace_insert(VARIADIC "any") returns integer Adds a filter to the list of session-tracing filters. A filter must be passed as a sequence of alternating key-value pairs, where the key is the name of the filter attribute from Table G.85 except
filter_id. For example:pgpro_stats_trace_insert('pid', 42, 'database_name', 'main', 'explain_analyze', true)Key-value pairs are position-independent: they can be provided in any order, independently of the order of attributes in Table G.85. Some of the attributes can be missing from the sequence. Such attributes will be assigned the default values. Returns the unique
filter_id, which the function assigns to the added filter.If some filter attribute is listed in the passed sequence more than once, the function fails.
Note that the function can finish normally, but return NULL, showing that the filter is not added. This happens, for example, if one of the filter attributes passed is NULL.
-
pgpro_stats_trace_update(filter_id integer, VARIADIC "any") returns boolean Updates a session-tracing filter defined by
filter_id. Filter attributes to update must be passed as a sequence of alternating key-value pairs, where the key is the name of the filter attribute from Table G.85 exceptfilter_id. Key-value pairs are position-independent: they can be provided in any order, independently of the order of attributes in Table G.85. Filter attributes whose values are not explicitly specified will not be changed. The value of NULL for identification and threshold attributes resets the values of these attributes, which means that a query will match the conditions of the updated filter regardless of the respective characteristics. Returnstrueon success andfalseotherwise.If some filter attribute is listed in the passed sequence more than once, the function fails.
-
pgpro_stats_trace_delete(filter_id integer) returns boolean Deletes a session-tracing filter defined by
filter_id. Returnstrueon success andfalseotherwise.-
pgpro_stats_trace_reset() returns integer Removes all session-tracing filters. Returns the number of removed filters. By default, this function can only be executed by superusers. Access may be granted to others using
GRANT.-
pgpro_stats_trace_show() returns setof record Displays the contents of the table of filters, whose columns are shown in Table G.85.
G.4.8.2. Session-Tracing Configuration Parameters #
The following parameters can be used to configure session-tracing logging. Note that pgpro_stats.explain_*_default settings define the logging behavior when the corresponding explain_* filter attributes (from Table G.85) are not specified or explicitly set to NULL.
-
pgpro_stats.explain_analyze_default(boolean) # If
true, theEXPLAINoutput will be logged with theANALYZEoption and without it iffalse. The default value isfalse. Only superusers can change this setting.-
pgpro_stats.explain_verbose_default(boolean) # If
true, theEXPLAINoutput will be logged with theVERBOSEoption and without it iffalse. The default value isfalse. Only superusers can change this setting.-
pgpro_stats.explain_costs_default(boolean) # If
true, theEXPLAINoutput will be logged with theCOSTSoption and without it iffalse. The default value istrue. Only superusers can change this setting.-
pgpro_stats.explain_settings_default(boolean) # If
true, theEXPLAINoutput will be logged with theSETTINGSoption and without it iffalse. The default value isfalse. Only superusers can change this setting.-
pgpro_stats.explain_buffers_default(boolean) # If
true, theEXPLAINoutput will be logged with theBUFFERSoption and without it iffalse. The default value isfalse. Only superusers can change this setting.-
pgpro_stats.explain_wal_default(boolean) # If
true, theEXPLAINoutput will be logged with theWALoption and without it iffalse. The default value isfalse. Only superusers can change this setting.-
pgpro_stats.explain_timing_default(boolean) # If
true, theEXPLAINoutput will be logged with theTIMINGoption and without it iffalse. The default value istrue. Only superusers can change this setting.-
pgpro_stats.trace_log_level(enum) # Defines the log level at which the
EXPLAINoutput will be logged to the system log file (when the trace file is not specified). Valid values areDEBUG,INFO,NOTICE,WARNING, andLOG. The default value isLOG.-
pgpro_stats.trace_query_text_size(int) # Defines the maximum size of query texts in the session-tracing output, in kilobytes. If the size of the query text in kilobytes is larger, it is trimmed to the maximum size. If this parameter is not specified, the default value of zero is used, which means that the whole query texts are output.
G.4.8.3. Examples Related to Session Tracing #
Example G.2. Usage of Session-Tracing Functions
Let's add the filter first:
SELECT pgpro_stats_trace_insert('alias', 'first', 'pid', pg_backend_pid(), 'explain_analyze', true);
Let's add the filter second and specify logging to the trace file second_tf.trace:
SELECT pgpro_stats_trace_insert('alias', 'second', 'database_name', current_database(), 'explain_costs', false, 'tracefile', 'second_tf');
You can view the table with filters as follows:
\x auto SELECT * FROM pgpro_stats_trace_show();
-[ RECORD 1 ]-------+---------- filter_id | 1 active | t alias | first tracefile | pid | 243183 database_name | client_addr | application_name | username | queryid | planid | duration | plan_time | exec_time | user_time | system_time | rows | shared_blks_hit | shared_blks_read | shared_blks_fetched | shared_blks_dirtied | shared_blks_written | local_blks_hit | local_blks_read | local_blks_fetched | local_blks_dirtied | local_blks_written | temp_blks_read | temp_blks_written | wal_bytes | total_wait_time | total_inval_msgs | explain_analyze | t explain_verbose | explain_costs | explain_settings | explain_buffers | explain_wal | explain_timing | explain_format | time_info | f -[ RECORD 2 ]-------+---------- filter_id | 2 active | t alias | second tracefile | second_tf pid | database_name | postgres client_addr | application_name | username | queryid | planid | duration | plan_time | exec_time | user_time | system_time | rows | shared_blks_hit | shared_blks_read | shared_blks_fetched | shared_blks_dirtied | shared_blks_written | local_blks_hit | local_blks_read | local_blks_fetched | local_blks_dirtied | local_blks_written | temp_blks_read | temp_blks_written | wal_bytes | total_wait_time | total_inval_msgs | explain_analyze | explain_verbose | explain_costs | f explain_settings | explain_buffers | explain_wal | explain_timing | explain_format | time_info | f
The following query matches the conditions of both filters, so it must be logged in the system log file and in the specified trace file:
SELECT 1 AS result;
The following is the output to the system log file:
2023-04-18 04:52:53.242 MSK [63112] LOG: Filter 1 triggered explain of the plan: Query Text: SELECT 1 AS result; Result (cost=0.00..0.01 rows=1 width=4) (actual time=0.003..0.003 rows=1 loops=1)
And the following is the output to the second_tf.trace trace file:
Query Text: SELECT 1 AS result; Result
Let's delete the first filter:
SELECT pgpro_stats_trace_delete(1);
Let's also change pid to 2 for the second filter
SELECT pgpro_stats_trace_update(2, 'pid', 2);
When you execute the query
SELECT 2 AS result;
it does not get logged to second_tf.trace.
Now let's remove all filters from the table:
SELECT pgpro_stats_trace_reset();
Example G.3. Session-Tracing Output with time_info = true
The following is an example of the session-tracing output in the JSON format when time_info = true:
{
"Pid": 123456,
"Duration ms": 0.094691,
"Start time": "2025-01-12 15:39:27.580447+03",
"Stop time": "2025-01-12 15:39:27.587802+03",
"Query Text": "SELECT 2 AS Result;",
"Plan": {
"Node Type": "Result",
"Parallel Aware": false,
"Async Capable": false,
"Startup Cost": 0.00,
"Total Cost": 0.01,
"Plan Rows": 1,
"Plan Width": 4
}
}
G.4.9. Cache Invalidation Metrics #
Among the rest, pgpro_stats can collect cache invalidation statistics. This section provides some background information needed to better understand related metrics.
Each backend has its local cache, which allows you to minimize accesses for meta information on tables, for example, to the system catalogs. If a backend changes the meta information, this information must be updated in other backends' caches. This is implemented by sending invalidation messages through a queue: the backend that changed the meta information on some object sends an appropriate message to the queue.
All backends get invalidation messages from the queue. Depending on whether the object for which the invalidation message was received is cached, the backend either ignores the message (when the object is not cached) or updates its cache (when the object is cached). In pgpro_stats, most invalidation message counters, unless explicitly stated otherwise for certain counters, are incremented when backends just generate messages, which will only be sent to the queue upon commit of the appropriate transaction. Note that the counters will remain incremented if the transaction is rolled back, although the message will not be sent to the queue.
When a backend that is adding messages to the queue figures out that the queue size reached a certain limit, it starts a cleanup by deleting messages already processed by all backends, and if backends are found that heavily fall behind and thus delay the cleanup, they get a reset signal, which forces them to reset all their caches.
G.4.9.1. The pgpro_stats_inval_status View #
The pgpro_stats_inval_status view shows one row with the current status of the cache invalidation global queue. The columns of the view are shown in Table G.86.
Table G.86. pgpro_stats_inval_status Columns
| Name | Type | Description |
|---|---|---|
num_inval_messages | int8 | Current number of invalidation messages in the queue |
num_inval_queue_cleanups | int8 | Number of invalidation queue cleanups done to prevent its overflow |
num_inval_queue_resets | int4 | Number of cache resets for backends that fail to process messages fast enough |
In a working system, num_inval_messages usually approximately equals 4000, which means that the queue is pretty full. The speed of the num_inval_queue_cleanups growth is determined by how fast invalidation messages are generated. Growth of num_inval_queue_resets is normally zero, and non-zero growth indicates either too fast generation of messages or delays in processing messages by backends. Monitoring num_inval_queue_cleanups and num_inval_queue_resets may in some cases allow you to detect problematic backend/backeds as described below.
If for a certain time interval, num_inval_queue_cleanups considerably increased, while num_inval_queue_resets did not, this indicates that invalidation messages are generated faster and/or backends process them more slowly, but backends still manage to process messages before the queue overflows.
If for a time interval, num_inval_queue_cleanups did not considerably increase, while num_inval_queue_resets did, this definitely indicates a delay in processing messages by backend(s), and the cache_resets column of the pgpro_stats_totals view allows you to figure out which backend(s) to blame.
If for a time interval, both counters considerably increased, this also indicates that invalidation messages are generated faster and/or backends process them more slowly, but this time backends fail to process messages before the queue overflows. The cache_resets column of the pgpro_stats_totals view allows you detect which backend(s) delay message processing. In this case, it is not possible to definitely conclude whether too fast generation of messages or a delay in message processing accounts for the growth of num_inval_queue_resets. However, the totals counter of the pgpro_stats_inval_msgs view may help here. If the change of this counter for that interval is pretty the same as for a previous interval of the same length, you can definitely conclude that the growth is caused by backend delays.
The pgpro_stats_inval_status view can be defined in terms of a function:
-
pgpro_stats_inval_status() returns record Defines the
pgpro_stats_inval_statusview, which is described in detail in Table G.86.
G.4.9.2. The pgpro_stats_inval_msgs Type #
The pgpro_stats_statements and pgpro_stats_totals views for each corresponding object, show a record of the pgpro_stats_inval_msgs record type containing counters for cache invalidation messages. The fields of the type are shown in Table G.87.
Table G.87. pgpro_stats_inval_msgs Fields
| Name | Type | Description |
|---|---|---|
total | bigint | Total number of invalidation messages |
catcache | bigint | Number of selective catalog cache invalidation messages |
catalog | bigint | Number of whole catalog cache invalidation messages |
relcache | bigint | Number of selective relation cache invalidation messages |
relcache_all | bigint | Number of whole relation cache invalidation messages |
smgr | bigint | Number of invalidation messages of open relation files. Gets incremented when the messages are sent to the queue. |
relmap | bigint | Number of relation map cache invalidation messages. Gets incremented when the messages are sent to the queue. |
snapshot | bigint | Number of catalog snapshot invalidation messages |
G.4.10. Authors #
Postgres Professional, Moscow, Russia