После того как расширение 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 | NULL

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

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

Статистика, собираемая модулем, выдаётся через представление с именем pgpro_stats_statements. Это представление содержит отдельные строки для каждой комбинации идентификатора базы данных, идентификатора пользователя и идентификатора запроса (но в количестве, не превышающем максимальное число различных операторов, которые может отслеживать модуль). Столбцы представления показаны в Таблице F.100.

Аналогично расширению 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 использует и для текстов планов. При этом делается попытка сопоставить номера констант в тексте плана соответствующим номерам констант в тексте запроса. Если такая попытка для какой-либо константы в тексте плана оканчивается неудачей, то ей присваивается следующий номер, больший максимального номера заменённой константы в тексте запроса. Например, для запроса:

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_totals. Это представление содержит отдельные строки для каждого отдельного объекта БД (но в количестве, не превышающем максимальное число различных объектов, которое может отслеживать модуль). Столбцы представления показаны в Таблице F.101.

Метрики, собранные модулем pgpro_stats, выводятся в представлении pgpro_stats_metrics. В таблице ниже описаны столбцы этого представления.

Представление pgpro_stats_archiver будет содержать одну строку, показывающую данные о процессе архивации кластера.

Представление pgpro_stats_vacuum_database будет содержать по одной строке для каждой базы данных в текущем кластере, показывая статистику очистки этой конкретной БД. Эта статистика собирается ядром системы, как описано в Разделе 27.2. В таблице ниже описаны столбцы представления.

Представление pgpro_stats_vacuum_tables будет содержать по одной строке для каждой таблицы в текущей базе данных (включая таблицы TOAST), показывая статистику очистки этой конкретной таблицы. Эта статистика собирается ядром системы, как описано в Разделе 27.2. В таблице ниже описаны столбцы представления.

Столбцы total_*, wal_* и blk_* содержат данные об очистке индексов этой таблицы, а столбцы system_time и user_time содержат только данные об очистке кучи.

Представление pgpro_stats_vacuum_indexes будет содержать одну строку для каждого индекса в текущей базе данных (включая индексы таблицы TOAST), показывая статистику очистки этого конкретного индекса. Эта статистика собирается ядром системы, как описано в Разделе 27.2. В таблице ниже описаны столбцы представления.

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

В расширении pgpro_stats реализована трассировка сеансов приложений. Она основана на фильтрах, которые запускают протоколирование выполнения запросов, соответствующих условиям фильтрации. Запросы и их планы записываются в так называемые файлы трассировки, указанные пользователем, или в файл системного журнала (если файл трассировки не указан). Фильтры хранятся в таблице, находящейся в общей памяти. Строки этой таблицы являются фильтрами, а столбцы содержат условия фильтрации. Чтобы начать трассировку запросов, следует заполнить эту таблицу фильтрами.

Как только администратор базы данных добавит фильтр в каком-либо сеансе, все последующие выполнения запросов, соответствующих условиям фильтра, будут трассироваться всеми сеансами экземпляра СУБД без необходимости перезапуска сервера. Другими словами, фильтры можно добавлять, удалять или изменять «на лету», и трассировка с этими фильтрами сразу же начнётся для существующих и будущих сеансов.

Каждый фильтр включает:

Специальные функции позволяют создавать, изменять и удалять фильтры запросов:

SELECT pgpro_stats_trace_insert('alias', 'first', 'pid', pg_backend_pid(), 'explain_analyze', true);

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     | f
 explain_costs       | t
 explain_settings    | f
 explain_buffers     | f
 explain_wal         | f
 explain_timing      | t
 explain_format      | text
 -[ 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     | f
 explain_verbose     | f
 explain_costs       | f
 explain_settings    | f
 explain_buffers     | f
 explain_wal         | f
 explain_timing      | f
 explain_format      | text

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)

Query Text: SELECT 1 as result;
Result

SELECT pgpro_stats_trace_delete(1);

SELECT pgpro_stats_trace_update(2, 'pid', 2);

SELECT 2 as result;

SELECT pgpro_stats_trace_reset();

В расширении 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 и выше. Эти представления могут быть созданы следующими функциями:

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

Для создания представлений 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;

Следующие параметры предназначены для определения дополнительных метрик, которые будет собирать pgpro_stats. Номер N в имени параметра служит уникальным идентификатором метрики, к которой будет применяться задаваемое значение; он должен быть положительным и уникальным среди всех метрик.

Если вы добавляете параметры для определения новой метрики, необходимо перезапустить сервер, чтобы это определение начало действовать. Когда метрика уже добавлена, её параметры можно изменять без перезапуска сервера, просто перезагружая файл конфигурации postgresql.conf.

Представление pgpro_stats_inval_status содержит одну строку, показывающую текущее состояние глобальной очереди аннулирования кеша. Столбцы представления показаны в Таблице F.109.

В работающей системе 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_statements и pgpro_stats_totals для каждого соответствующего объекта показывают запись типа pgpro_stats_inval_msgs со счётчиками сообщений аннулирования кеша. Поля этой записи показаны в Таблице F.110.