Add optional no-query-text pg_stat_statements collectors

changelogs/fragments/pg-stat-statements-query-text.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Add optional postgres_exporter collectors that avoid loading retained ``pg_stat_statements`` query text. The ``query`` label is retained with an empty value for compatibility; use ``queryid`` to inspect query text in PostgreSQL when needed.

hugo/content/exporter/_index.md

@@ -590,6 +590,7 @@ Note that {{< shell >}}/etc/sysconfig/postgres_exporter_pg##{{< /shell >}} & {{<
 | queries_backrest.yml | postgres_exporter query file for monitoring pgBackRest backup status. By default, new backrest data is only collected every 10 minutes to avoid excessive load when there are large backup lists. See sysconfig file for exporter service to adjust this throttling. |
 | queries_pgbouncer.yml | postgres_exporter query file for monitoring pgbouncer. |
 | queries_pg_stat_statements.yml | postgres_exporter query file for specific pg_stat_statements metrics that are most useful for monitoring and trending. |
+| queries_pg_stat_statements_no_query_text.yml | Alternative pg_stat_statements query file that avoids loading retained query text. The `query` label is empty, but `queryid` remains available. |
 
 
 By default, there are two postgres_exporter services expected to be running. One connects to the default {{< shell >}}postgres{{< /shell >}} database that most PostgreSQL instances come with and is meant for collecting global metrics that are the same on all databases in the instance (connection/replication statistics, etc). This service uses the sysconfig file {{< shell >}}postgres_exporter_pg##{{< /shell >}}. Connect to this database and run the setup.sql script to install the required database objects for pgMonitor.
@@ -600,6 +601,8 @@ Note that your pg_hba.conf will have to be configured to allow the {{< shell >}}
 
 postgres_exporter only takes a single yaml file as an argument for custom queries, so this requires concatenating the relevant files together. The sysconfig files for the service help with this concatenation task and define the variable {{< yaml >}}QUERY_FILE_LIST{{< /yaml >}}. Set this variable to a space delimited list of the full path names to all files that contain queries you want to be in the single file that postgres_exporter uses.
 
+To collect pg_stat_statements metrics, add either {{< shell >}}queries_pg_stat_statements.yml{{< /shell >}} or {{< shell >}}queries_pg_stat_statements_no_query_text.yml{{< /shell >}} to {{< yaml >}}QUERY_FILE_LIST{{< /yaml >}}, but not both. The standard file exports the first 40 characters of each top statement. The no-query-text variant uses `pg_stat_statements(false)` so PostgreSQL does not load retained query text during collection, and exports an empty {{< yaml >}}query{{< /yaml >}} label. Use the {{< yaml >}}queryid{{< /yaml >}} label to inspect the full statement in PostgreSQL when needed.
+
 For example, to use just the common queries for PostgreSQL 12 modify the relevant sysconfig file as follows:
 
 ```bash

postgres_exporter/common/pg13/queries_pg_stat_statements_no_query_text.yml

@@ -0,0 +1,172 @@
+###
+#
+# Begin File: PG13 queries_pg_stat_statements_no_query_text.yml
+#
+# Copyright © 2017-2025 Crunchy Data Solutions, Inc. All Rights Reserved.
+# Copyright © 2025-2026 Snowflake, Inc. All Rights Reserved.
+#
+###
+
+ccp_pg_stat_statements_total:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              sum(s.calls) AS calls_count,
+              sum(s.total_exec_time) AS exec_time_ms,
+              avg(s.mean_exec_time) AS mean_exec_time_ms,
+              sum(s.rows) AS row_count
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          GROUP BY 1,2"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - calls_count:
+        usage: "GAUGE"
+        description: "Total number of queries run per user/database"
+    - exec_time_ms:
+        usage: "GAUGE"
+        description: "Total runtime of all queries per user/database"
+    - mean_exec_time_ms:
+        usage: "GAUGE"
+        description: "Mean runtime of all queries per user/database"
+    - row_count:
+        usage: "GAUGE"
+        description: "Total rows returned from all queries per user/database"
+
+
+ccp_pg_stat_statements_top_mean:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              s.queryid,
+              '' AS query,
+              max(s.mean_exec_time) exec_time_ms
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          GROUP BY 1,2,3,4
+          ORDER BY 5 DESC
+          LIMIT #PG_STAT_STATEMENTS_LIMIT#"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - queryid:
+        usage: "LABEL"
+        description: "Internal hash code, computed from the statement's parse tree"
+    - query:
+        usage: "LABEL"
+        description: "Empty label retained for metric compatibility"
+    - exec_time_ms:
+        usage: "GAUGE"
+        description: "Average query runtime in milliseconds"
+
+
+# Note that individual query stats can only be reset in PG12
+ccp_pg_stat_statements_top_total:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              s.queryid,
+              '' AS query,
+              s.total_exec_time exec_time_ms
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          ORDER BY 5 DESC
+          LIMIT #PG_STAT_STATEMENTS_LIMIT#"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - queryid:
+        usage: "LABEL"
+        description: "Internal hash code, computed from the statement's parse tree"
+    - query:
+        usage: "LABEL"
+        description: "Empty label retained for metric compatibility"
+    - exec_time_ms:
+        usage: "GAUGE"
+        description: "Total time spent in the statement in milliseconds"
+
+
+# Note that individual query stats can only be reset in PG12
+ccp_pg_stat_statements_top_max:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              s.queryid,
+              '' AS query,
+              s.max_exec_time AS exec_time_ms
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          ORDER BY 5 DESC
+          LIMIT #PG_STAT_STATEMENTS_LIMIT#"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - queryid:
+        usage: "LABEL"
+        description: "Internal hash code, computed from the statement's parse tree"
+    - query:
+        usage: "LABEL"
+        description: "Empty label retained for metric compatibility"
+    - exec_time_ms:
+        usage: "GAUGE"
+        description: "Maximum time spent in the statement in milliseconds"
+
+
+ccp_pg_stat_statements_top_wal:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              s.queryid,
+              '' AS query,
+              s.wal_records AS records,
+              s.wal_fpi AS fpi,
+              s.wal_bytes AS bytes
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          ORDER BY s.wal_bytes DESC
+          LIMIT #PG_STAT_STATEMENTS_LIMIT#"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - queryid:
+        usage: "LABEL"
+        description: "Internal hash code, computed from the statement's parse tree"
+    - query:
+        usage: "LABEL"
+        description: "Empty label retained for metric compatibility"
+    - records:
+        usage: "GAUGE"
+        description: "Total number of WAL records generated by the statement"
+    - fpi:
+        usage: "GAUGE"
+        description: "Total number of WAL full page images generated by the statement"
+    - bytes:
+        usage: "GAUGE"
+        description: "Total amount of WAL generated by the statement in bytes"
+
+###
+#
+# End File: PG13 queries_pg_stat_statements_no_query_text.yml
+#
+###

postgres_exporter/common/pg14/queries_pg_stat_statements_no_query_text.yml

@@ -0,0 +1,170 @@
+###
+#
+# Begin File: PG14 queries_pg_stat_statements_no_query_text.yml
+#
+# Copyright © 2017-2025 Crunchy Data Solutions, Inc. All Rights Reserved.
+# Copyright © 2025-2026 Snowflake, Inc. All Rights Reserved.
+#
+###
+
+ccp_pg_stat_statements_total:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              sum(s.calls) AS calls_count,
+              sum(s.total_exec_time) AS exec_time_ms,
+              avg(s.mean_exec_time) AS mean_exec_time_ms,
+              sum(s.rows) AS row_count
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          GROUP BY 1,2"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - calls_count:
+        usage: "GAUGE"
+        description: "Total number of queries run per user/database"
+    - exec_time_ms:
+        usage: "GAUGE"
+        description: "Total runtime of all queries per user/database"
+    - mean_exec_time_ms:
+        usage: "GAUGE"
+        description: "Mean runtime of all queries per user/database"
+    - row_count:
+        usage: "GAUGE"
+        description: "Total rows returned from all queries per user/database"
+
+
+ccp_pg_stat_statements_top_mean:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              s.queryid,
+              '' AS query,
+              max(s.mean_exec_time) exec_time_ms
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          GROUP BY 1,2,3,4
+          ORDER BY 5 DESC
+          LIMIT #PG_STAT_STATEMENTS_LIMIT#"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - queryid:
+        usage: "LABEL"
+        description: "Internal hash code, computed from the statement's parse tree"
+    - query:
+        usage: "LABEL"
+        description: "Empty label retained for metric compatibility"
+    - exec_time_ms:
+        usage: "GAUGE"
+        description: "Average query runtime in milliseconds"
+
+
+ccp_pg_stat_statements_top_total:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              s.queryid,
+              '' AS query,
+              s.total_exec_time exec_time_ms
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          ORDER BY 5 DESC
+          LIMIT #PG_STAT_STATEMENTS_LIMIT#"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - queryid:
+        usage: "LABEL"
+        description: "Internal hash code, computed from the statement's parse tree"
+    - query:
+        usage: "LABEL"
+        description: "Empty label retained for metric compatibility"
+    - exec_time_ms:
+        usage: "GAUGE"
+        description: "Total time spent in the statement in milliseconds"
+
+
+ccp_pg_stat_statements_top_max:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              s.queryid,
+              '' AS query,
+              s.max_exec_time AS exec_time_ms
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          ORDER BY 5 DESC
+          LIMIT #PG_STAT_STATEMENTS_LIMIT#"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - queryid:
+        usage: "LABEL"
+        description: "Internal hash code, computed from the statement's parse tree"
+    - query:
+        usage: "LABEL"
+        description: "Empty label retained for metric compatibility"
+    - exec_time_ms:
+        usage: "GAUGE"
+        description: "Maximum time spent in the statement in milliseconds"
+
+
+ccp_pg_stat_statements_top_wal:
+  query: "SELECT pg_get_userbyid(s.userid) as role,
+              d.datname AS dbname,
+              s.queryid,
+              '' AS query,
+              s.wal_records AS records,
+              s.wal_fpi AS fpi,
+              s.wal_bytes AS bytes
+          FROM public.pg_stat_statements(false) s
+          JOIN pg_catalog.pg_database d
+          ON d.oid = s.dbid
+          ORDER BY s.wal_bytes DESC
+          LIMIT #PG_STAT_STATEMENTS_LIMIT#"
+  metrics:
+    - role:
+        usage: "LABEL"
+        description: "Role that executed the statement"
+    - dbname:
+        usage: "LABEL"
+        description: "Database in which the statement was executed"
+    - queryid:
+        usage: "LABEL"
+        description: "Internal hash code, computed from the statement's parse tree"
+    - query:
+        usage: "LABEL"
+        description: "Empty label retained for metric compatibility"
+    - records:
+        usage: "GAUGE"
+        description: "Total number of WAL records generated by the statement"
+    - fpi:
+        usage: "GAUGE"
+        description: "Total number of WAL full page images generated by the statement"
+    - bytes:
+        usage: "GAUGE"
+        description: "Total amount of WAL generated by the statement in bytes"
+
+###
+#
+# End File: PG14 queries_pg_stat_statements_no_query_text.yml
+#
+###