Все статистические данные, собранные модулем, доступны через представление с именем pg_stat_statements. Это представление содержит одну строку для каждой уникальной комбинации идентификатора базы данных, идентификатора пользователя, идентификатора запроса и указания, является ли он верхнеуровневым оператором или нет (до максимального количества уникальных операторов, которое может отслеживать модуль). Столбцы представления показаны в Таблица F.22.

Для обеспечения безопасности, только суперпользователи и роли с привилегиями роли pg_read_all_stats могут видеть SQL-текст и queryid запросов, выполненных другими пользователями. Однако, другие пользователи могут видеть статистику, если представление было установлено в их базе данных.

Планируемые запросы (то есть, SELECT, INSERT, UPDATE, DELETE и MERGE) и утилитные команды объединяются в одну запись pg_stat_statements, если у них идентичные структуры запросов согласно внутреннему вычислению хеша. Как правило, два запроса будут считаться одинаковыми для этой цели, если они семантически эквивалентны, за исключением значений литеральных констант, появляющихся в запросе.

Когда значение константы было проигнорировано для целей сопоставления запроса с другими запросами, константа заменяется символом параметра, таким как $1, в отображении pg_stat_statements. Остальной текст запроса является текстом первого запроса, у которого есть определенное значение хеша queryid, связанное с записью pg_stat_statements.

Запросы, к которым может быть применена нормализация, могут наблюдаться с постоянными значениями в pg_stat_statements, особенно когда наблюдается высокая частота освобождения записей. Чтобы уменьшить вероятность этого, рассмотрите возможность увеличения pg_stat_statements.max. Представление pg_stat_statements_info, обсуждаемое ниже в Раздел F.47.2, предоставляет статистику об освобождении записей.

В некоторых случаях запросы с явно разным текстом могут быть объединены в одну запись pg_stat_statements. Обычно это происходит только для семантически эквивалентных запросов, но существует небольшая вероятность коллизий хешей, из-за которых несвязанные запросы могут быть объединены в одну запись. (Однако это не может произойти для запросов, принадлежащих разным пользователям или базам данных).

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

Потребители pg_stat_statements могут захотеть использовать queryid (возможно, в сочетании с dbid и userid) в качестве более стабильного и надежного идентификатора для каждой записи, чем ее текст запроса. Однако важно понимать, что существуют только ограниченные гарантии стабильности хеш-значения queryid. Поскольку идентификатор производится из дерева после анализа разбора, его значение является функцией, среди прочего, внутренних идентификаторов объектов, появляющихся в этом представлении. Это имеет некоторые контринтуитивные последствия. Например, pg_stat_statements будет считать два, на первый взгляд, идентичных запроса разными, если они ссылается на таблицу, которая была удалена и воссоздана между выполнением двух запросов. Процесс хеширования также чувствителен к различиям в архитектуре машины и другим аспектам платформы. Кроме того, нельзя считать, что queryid будет стабильным в разных основных версиях Tantor SE-1C.

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

В общем, можно предположить, что значения queryid стабильны между минорными версиями Tantor SE-1C, при условии, что экземпляры работают на одной и той же архитектуре машины и детали метаданных каталога совпадают. Совместимость будет нарушена между минорными версиями только в крайнем случае.

Все символы параметров, используемые для замены констант в текстах представительных запросов, начинаются с номера, следующего за наивысшим значением параметра $n в исходном тексте запроса, или $1, если такого параметра не было. Следует отметить, что в некоторых случаях могут быть скрытые символы параметров, которые влияют на эту нумерацию. Например, PL/pgSQL использует скрытые символы параметров для вставки значений локальных переменных функции в запросы, так что оператор PL/pgSQL вроде SELECT i + 1 INTO j будет иметь представительный текст вроде SELECT i + $2.

Все тексты запросов хранятся во внешнем файле на диске и не используют общую память. Поэтому даже очень длинные тексты запросов могут быть успешно сохранены. Однако, если накапливается много длинных текстов запросов, внешний файл может стать неуправляемо большим. В случае возникновения такой ситуации, pg_stat_statements может выбрать отказаться от хранения текстов запросов, в результате чего все существующие записи в представлении pg_stat_statements будут иметь пустые поля query, хотя статистика, связанная с каждым queryid, будет сохранена. Если это произойдет, рассмотрите возможность снижения значения pg_stat_statements.max для предотвращения повторения такой ситуации.

plans и calls не всегда ожидаются совпадать, потому что статистика планирования и выполнения обновляется в соответствующей конечной фазе и только для успешных операций. Например, если операция успешно запланирована, но не удалось выполнить во время фазы выполнения, будет обновлена только статистика планирования. Если планирование прне указано из-за использования кешированного плана, будет обновлена только статистика выполнения.

Статистика модуля pg_stat_statements отслеживается и доступна через представление с именем pg_stat_statements_info. Это представление содержит только одну строку. Столбцы представления показаны в Таблица F.23.

Модуль требует дополнительную общую память, пропорциональную pg_stat_statements.max. Обратите внимание, что эта память расходуется при каждой загрузке модуля, даже если pg_stat_statements.track установлено в none.

Эти параметры должны быть установлены в файле postgresql.conf. Обычное использование может быть таким:

# postgresql.conf
shared_preload_libraries = 'pg_stat_statements'

compute_query_id = on
pg_stat_statements.max = 10000
pg_stat_statements.track = all

bench=# SELECT pg_stat_statements_reset();

$ pgbench -i bench
$ pgbench -c10 -t300 bench

bench=# \x
bench=# SELECT query, calls, total_exec_time, rows, 100.0 * shared_blks_hit /
               nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent
          FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;
-[ RECORD 1 ]---+--------------------------------------------------​------------------
query           | UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2
calls           | 3000
total_exec_time | 25565.855387
rows            | 3000
hit_percent     | 100.0000000000000000
-[ RECORD 2 ]---+--------------------------------------------------​------------------
query           | UPDATE pgbench_tellers SET tbalance = tbalance + $1 WHERE tid = $2
calls           | 3000
total_exec_time | 20756.669379
rows            | 3000
hit_percent     | 100.0000000000000000
-[ RECORD 3 ]---+--------------------------------------------------​------------------
query           | copy pgbench_accounts from stdin
calls           | 1
total_exec_time | 291.865911
rows            | 100000
hit_percent     | 100.0000000000000000
-[ RECORD 4 ]---+--------------------------------------------------​------------------
query           | UPDATE pgbench_accounts SET abalance = abalance + $1 WHERE aid = $2
calls           | 3000
total_exec_time | 271.232977
rows            | 3000
hit_percent     | 98.8454011741682975
-[ RECORD 5 ]---+--------------------------------------------------​------------------
query           | alter table pgbench_accounts add primary key (aid)
calls           | 1
total_exec_time | 160.588563
rows            | 0
hit_percent     | 100.0000000000000000


bench=# SELECT pg_stat_statements_reset(0,0,s.queryid) FROM pg_stat_statements AS s
            WHERE s.query = 'UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2';

bench=# SELECT query, calls, total_exec_time, rows, 100.0 * shared_blks_hit /
               nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent
          FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;
-[ RECORD 1 ]---+--------------------------------------------------​------------------
query           | UPDATE pgbench_tellers SET tbalance = tbalance + $1 WHERE tid = $2
calls           | 3000
total_exec_time | 20756.669379
rows            | 3000
hit_percent     | 100.0000000000000000
-[ RECORD 2 ]---+--------------------------------------------------​------------------
query           | copy pgbench_accounts from stdin
calls           | 1
total_exec_time | 291.865911
rows            | 100000
hit_percent     | 100.0000000000000000
-[ RECORD 3 ]---+--------------------------------------------------​------------------
query           | UPDATE pgbench_accounts SET abalance = abalance + $1 WHERE aid = $2
calls           | 3000
total_exec_time | 271.232977
rows            | 3000
hit_percent     | 98.8454011741682975
-[ RECORD 4 ]---+--------------------------------------------------​------------------
query           | alter table pgbench_accounts add primary key (aid)
calls           | 1
total_exec_time | 160.588563
rows            | 0
hit_percent     | 100.0000000000000000
-[ RECORD 5 ]---+--------------------------------------------------​------------------
query           | vacuum analyze pgbench_accounts
calls           | 1
total_exec_time | 136.448116
rows            | 0
hit_percent     | 99.9201915403032721

bench=# SELECT pg_stat_statements_reset(0,0,0);

bench=# SELECT query, calls, total_exec_time, rows, 100.0 * shared_blks_hit /
               nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent
          FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;
-[ RECORD 1 ]---+--------------------------------------------------​---------------------------
query           | SELECT pg_stat_statements_reset(0,0,0)
calls           | 1
total_exec_time | 0.189497
rows            | 1
hit_percent     |
-[ RECORD 2 ]---+--------------------------------------------------​---------------------------
query           | SELECT query, calls, total_exec_time, rows, $1 * shared_blks_hit /          +
                |                nullif(shared_blks_hit + shared_blks_read, $2) AS hit_percent+
                |           FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT $3
calls           | 0
total_exec_time | 0
rows            | 0
hit_percent     |

Takahiro Itagaki <itagaki.takahiro@oss.ntt.co.jp>. Нормализация запроса добавлена Питером Геогеганом <peter@2ndquadrant.com>.