PostgreSQL插件-pg_stat_statements-安装和使用

---

pg_stat_statements模块提供了一种跟踪服务器执行的所有 SQL 语句的规划和执行统计信息的方法。

pg_stat_statements模块必须通过将其添加到postgresql.conf中的 shared_preload_libraries来加载该模块，因为它需要额外的共享内存。这意味着需要重新启动服务器才能添加或删除模块。此外，必须启用查询标识符计算才能使模块处于活动状态，如果将 compute_query_id 设置为auto或 on，或者加载任何计算查询标识符的第三方模块，则会自动完成该计算。

当pg_stat_statements处于活动状态时，它将跟踪服务器所有数据库的统计信息。要访问和操作这些统计信息，该模块提供了视图pg_stat_statements和 pg_stat_statements_info，以及实用程序函数 pg_stat_statements_reset 和 pg_stat_statements 。

这些功能在全局范围内不可用，但可以使用 CREATE EXTENSION pg_stat_statements 为特定数据库启用。

F.30.1. 视图pg_stat_statements

模块收集的统计信息可通过名为 pg_stat_statements 的视图提供。对于数据库 ID、用户 ID、查询 ID 以及它是否为顶级语句（最多为模块可以跟踪的最大非重复语句数），此视图包含一行。视图的列如 表 F.21 所示。

表 F.21.pg_stat_statements列

列类型描述
userid oid（参考资料pg_authid。oid)执行语句的用户的 OID
dbid oid（参考资料pg_database。oid)执行语句的数据库的 OID
toplevel bool如果查询作为顶级语句执行，则为 true（如果设置为pg_stat_statements.track``top)
queryid bigint用于标识相同规范化查询的哈希代码。
query text代表发言稿
plans bigint计划语句的次数（如果启用，则为零）pg_stat_statements.track_planning
total_plan_time double precision计划语句所花费的总时间，以毫秒为单位（如果启用，则为零）pg_stat_statements.track_planning
min_plan_time double precision计划语句所花费的最短时间（以毫秒为单位）（如果启用，则为零）pg_stat_statements.track_planning
max_plan_time double precision计划语句所花费的最长时间（以毫秒为单位）（如果启用，则为零）pg_stat_statements.track_planning
mean_plan_time double precision计划语句的平均时间，以毫秒为单位（如果启用，则为零）pg_stat_statements.track_planning
stddev_plan_time double precision计划语句所花时间的总体标准差，以毫秒为单位（如果启用，则为零）pg_stat_statements.track_planning
calls bigint语句的执行次数
total_exec_time double precision执行语句所花费的总时间（以毫秒为单位）
min_exec_time double precision执行语句所花费的最短时间（以毫秒为单位）
max_exec_time double precision执行语句所花费的最长时间（以毫秒为单位）
mean_exec_time double precision执行语句所花费的平均时间（以毫秒为单位）
stddev_exec_time double precision执行语句所花时间的总体标准偏差（以毫秒为单位）
rows bigint语句检索或影响的总行数
shared_blks_hit bigint语句的共享块缓存命中总数
shared_blks_read bigint语句读取的共享块总数
shared_blks_dirtied bigint语句弄脏的共享块的总数
shared_blks_written bigint语句写入的共享块总数
local_blks_hit bigint语句的本地块缓存命中总数
local_blks_read bigint语句读取的本地块总数
local_blks_dirtied bigint语句弄脏的本地块的总数
local_blks_written bigint语句写入的本地块的总数
temp_blks_read bigint语句读取的临时块总数
temp_blks_written bigint语句写入的临时块总数
blk_read_time double precision语句读取块所花费的总时间，以毫秒为单位（如果启用了track_io_timing，否则为零）
blk_write_time double precision语句写入块所花费的总时间，以毫秒为单位（如果启用了track_io_timing，否则为零）
wal_records bigint语句生成的 WAL 记录总数
wal_fpi bigint语句生成的 WAL 整页图像总数
wal_bytes numeric语句生成的 WAL 总量（以字节为单位）

出于安全原因，仅允许超级用户和角色成员 pg_read_all_stats 查看 SQL 文本和 queryid 其他用户执行的查询。但是，如果视图已安装在其数据库中，则其他用户可以看到统计信息。

根据内部哈希计算，只要可计划的查询（即、SELECT INSERT UPDATE、和DELETE）具有相同的pg_stat_statements查询结构，它们就会合并为一个条目。通常，如果两个查询在语义上是等效的，则对于此目的，除了查询中出现的文本常量的值之外，它们将被视为相同。但是，实用程序命令（即所有其他命令）严格根据其文本查询字符串进行比较。

注意

以下有关常量替换和queryid的详细信息，仅当启用compute_query_id时才适用。如果使用外部模块代替计算queryid ，则应参阅其文档以了解详细信息。

当为了将查询与其他查询匹配而忽略常量的值时，该常量将替换为显示中的参数符号，如$1 。查询文本pg_stat_statements的其余部分是具有与条目关联的特定queryid哈希值的第一个查询的pg_stat_statements文本。

在某些情况下，具有明显不同文本的查询可能会合并到单个pg_stat_statements条目中。通常，这只会发生在语义上等效的查询中，但哈希冲突导致不相关的查询合并到一个条目中的可能性很小。（但是，对于属于不同用户或数据库的查询，不会发生这种情况。

由于queryid哈希值是根据查询的分析后分析表示形式计算的，因此也可能相反：如果由于设置不同的因素而具有不同含义，例如不同的search_path，则具有相同文本的查询可能显示为单独的条目。

pg_stat_statements的使用者可能希望使用queryid（可能与 dbid 和 userid 结合使用）作为每个条目的比其查询文本更稳定和可靠的标识符。但是，重要的是要了解queryid哈希值的稳定性只有有限的保证。由于标识符派生自解析后分析树，因此其值是此表示形式中出现的内部对象标识符的函数。其中包括。这有一些违反直觉的含义。例如，如果两个明显相同的查询引用了在两个查询的执行之间删除并重新创建的表，pg_stat_statements则会认为它们是不同的。哈希过程对机器架构和平台其他方面的差异也很敏感。此外，假设它在PostgreSQL的主要版本中是稳定的queryid，这并不安全。

根据经验，只要基础服务器版本和目录元数据详细信息保持完全相同，就可以假定queryid值是稳定且可比较的。参与基于物理 WAL 重播的复制的两台服务器对于同一查询可能具有相同的queryid值。但是，逻辑复制方案不承诺在所有相关细节上保持副本相同，因此queryid不会成为跨一组逻辑副本累积成本的有用标识符。如有疑问，建议直接检查。

用于替换代表性查询文本中常量的参数符号从原始查询文本中最高 *$n 个*参数之后的下一个数字开始，如果没有，则从下一个数字$1开始。值得注意的是，在某些情况下，可能存在影响此编号的隐藏参数符号。例如 SELECT i + 1 INTO j，PL/pgSQL 使用隐藏参数符号将函数局部变量的值插入到查询中，以便 PL/pgSQL 语句具有像 SELECT i + $2。

代表性查询文本保存在外部磁盘文件中，并且不占用共享内存。因此，即使是非常长的查询文本也可以成功存储。但是，如果累积了许多长查询文本，则外部文件可能会变得非常大。作为一种恢复方法，如果发生这种情况，pg_stat_statements可以选择丢弃查询文本，从而pg_stat_statements视图中的所有现有条目将显示空query字段，尽管保留了与每个queryid字段关联的统计信息。如果发生这种情况，请考虑减少pg_stat_statements.max以防止复发。

plans和calls并不总是期望匹配，因为规划和执行统计信息在其各自的结束阶段更新，并且仅用于成功的操作。例如，如果语句已成功计划，但在执行阶段失败，则只会更新其计划统计信息。如果由于使用了缓存的计划而跳过计划，则只会更新其执行统计信息。

F.30.2. 视图pg_stat_statements_info

pg_stat_statements模块本身的统计信息被跟踪，并通过名为 pg_stat_statements_info 的视图提供。此视图仅包含一行。视图的列如表 F.22 所示。

表 F.22.pg_stat_statements_info列

列类型描述
dealloc bigint有关执行最少的语句的pg_stat_statements条目被解除分配的总次数，因为不同的语句比观察到的pg_stat_statements.max要多
stats_reset timestamp with time zone上次重置pg_stat_statements视图中所有统计信息的时间。

F.30.3. 函数

• pg_stat_statements_reset(userid Oid, dbid Oid, queryid bigint) returns void

  pg_stat_statements_reset丢弃到目前为止通过对应于指定的 userid ,dbid和 queryid收集的pg_stat_statements统计信息。如果未指定任何参数，则对每个参数使用默认值0（无效），并且将重置与其他参数匹配的统计信息。如果未指定任何参数或所有指定的参数都0（无效），则将丢弃所有统计信息。如果pg_stat_statements视图中的所有统计信息都被丢弃，则还会重置pg_stat_statements_info视图中的统计信息。默认情况下，此功能只能由超级用户执行。可以使用 GRANT 向其他人授予访问权限。

• pg_stat_statements(showtext boolean) returns setof record

  pg_stat_statements该视图是根据一个名为 pg_stat_statements 的函数定义的。客户端可以直接调用该函数pg_stat_statements，并通过指定省略查询文本showtext := false（即OUT，与视图列对应的参数query将返回 null）。此功能旨在支持外部工具，这些工具可能希望避免重复检索不确定长度的查询文本的开销。此类工具可以改为缓存为每个条目本身观察到的第一个查询文本，因为这是它本身pg_stat_statements所做的，然后仅在需要时检索查询文本。由于服务器将查询文本存储在文件中，因此此方法可能会减少重复检查pg_stat_statements数据的物理 I/O。

F.30.4. 配置参数

• pg_stat_statements.max（整数）

  pg_stat_statements.max是模块跟踪的最大语句数（即pg_stat_statements视图中的最大行数）。如果观察到的语句不同于此值，则将丢弃有关执行最少的语句的信息。在pg_stat_statements_info视图中可以看到丢弃此类信息的次数。默认值为 5000。此参数只能在服务器启动时设置。

• pg_stat_statements.track （enum）

  pg_stat_statements.track控制模块对哪些语句进行计数。top指定跟踪顶级语句（由客户端直接发出的语句）、all跟踪嵌套语句（如在函数中调用的语句）或none禁用语句统计信息收集。缺省值为top 。只有超级用户可以更改此设置。

• pg_stat_statements.track_utility （boolean）

  pg_stat_statements.track_utility控制模块是否跟踪实用程序命令。实用程序命令是 除 SELECT、INSERT、UPDATE 和 DELETE以外的所有命令。缺省值为on 。只有超级用户可以更改此设置。

• pg_stat_statements.track_planning （boolean）

  pg_stat_statements.track_planning控制模块是否跟踪计划操作和工期。启用此参数可能会产生明显的性能损失，尤其是当具有相同查询结构的语句由许多并发连接执行时，这些并发连接争用更新少量pg_stat_statements条目。缺省值为 off。只有超级用户可以更改此设置。

• pg_stat_statements.save （布尔值）

  pg_stat_statements.save指定是否在服务器关闭时保存语句统计信息。如果是off，则不会在关机时保存统计信息，也不会在服务器启动时重新加载统计信息。缺省值为 on。此参数只能在postgresql.conf文件中或在服务器命令行中设置。

该模块需要与 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

F.30.5. 示例输出

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     | 

F.30.6. 作者

板垣孝宏 .由 Peter Geoghegan 添加的查询规范化。<itagaki.takahiro@oss.ntt.co.jp>，<peter@2ndquadrant.com>

---

原文：https://www.postgresql.org/docs/14/pgstatstatements.html

最新版本详见：https://www.postgresql.org/docs/current/pgstatstatements.html