From e96b697adb138b0bbe34082761b4e4538abcc9e6 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 5 Oct 2015 12:44:12 -0400
Subject: [PATCH] Docs: explain contrib/pg_stat_statements' handling of GC
failure.
Failure to perform garbage collection now has a user-visible effect, so
explain that and explain that reducing pgss_max is the way to prevent it.
Per gripe from Andrew Dunstan.
---
doc/src/sgml/pgstatstatements.sgml | 18 ++++++++++++++++--
1 file changed, 16 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/pgstatstatements.sgml b/doc/src/sgml/pgstatstatements.sgml
index a58ecf7065f..ca9478acdf6 100644
--- a/doc/src/sgml/pgstatstatements.sgml
+++ b/doc/src/sgml/pgstatstatements.sgml
@@ -242,7 +242,7 @@
</para>
<para>
- Consumers of <literal>pg_stat_statements</> may wish to use
+ Consumers of <structname>pg_stat_statements</> may wish to use
<structfield>queryid</> (perhaps in combination with
<structfield>dbid</> and <structfield>userid</>) as a more stable
and reliable identifier for each entry than its query text.
@@ -252,7 +252,7 @@
post-parse-analysis tree, its value is a function of, among other
things, the internal object identifiers appearing in this representation.
This has some counterintuitive implications. For example,
- <literal>pg_stat_statements</> will consider two apparently-identical
+ <filename>pg_stat_statements</> will consider two apparently-identical
queries to be distinct, if they reference a table that was dropped
and recreated between the executions of the two queries.
The hashing process is also sensitive to differences in
@@ -272,6 +272,20 @@
not be a useful identifier for accumulating costs across a set of logical
replicas. If in doubt, direct testing is recommended.
</para>
+
+ <para>
+ The representative query texts are kept in an external disk file, and do
+ not consume shared memory. Therefore, even very lengthy query texts can
+ be stored successfully. However, if many long query texts are
+ accumulated, the external file might grow unmanageably large. As a
+ recovery method if that happens, <filename>pg_stat_statements</> may
+ choose to discard the query texts, whereupon all existing entries in
+ the <structname>pg_stat_statements</> view will show
+ null <structfield>query</> fields, though the statistics associated with
+ each <structfield>queryid</> are preserved. If this happens, consider
+ reducing <varname>pg_stat_statements.max</varname> to prevent
+ recurrences.
+ </para>
</sect2>
<sect2>
--
GitLab