pgstat: Update docs to match the shared memory stats reality.

anarazel · anarazel · commit b3abca68106d · 2022-04-07T21:35:35.000-07:00
This includes removing documentation for stats_temp_directory, adding documentation for stats_fetch_consistency, rephrasing references to the stats collector and documenting that starting a cleanly shut down standby will not remove stats anymore. The latter point might require further wordsmithing, it wasn't easy to adjust some of the existing content. Author: Kyotaro Horiguchi <horikyota.ntt@gmail.com> Author: Andres Freund <andres@anarazel.de> Reviewed-By: Thomas Munro <thomas.munro@gmail.com> Reviewed-By: Justin Pryzby <pryzby@telsasoft.com> Reviewed-By: "David G. Johnston" <david.g.johnston@gmail.com> Reviewed-By: Lukas Fittl <lukas@fittl.com> Discussion: https://postgr.es/m/20220303021600.hs34ghqcw6zcokdh@alap3.anarazel.de
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
@@ -1036,8 +1036,6 @@ SELECT * FROM pg_backup_stop(wait_for_archive => true);
     <filename>pg_snapshots/</filename>, <filename>pg_stat_tmp/</filename>,
     and <filename>pg_subtrans/</filename> (but not the directories themselves) can be
     omitted from the backup as they will be initialized on postmaster startup.
-    If <xref linkend="guc-stats-temp-directory"/> is set and is under the data
-    directory then the contents of that directory can also be omitted.
    </para>
 
    <para>
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
@@ -9593,9 +9593,9 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
   <para>
    <xref linkend="view-table"/> lists the system views described here.
    More detailed documentation of each view follows below.
-   There are some additional views that provide access to the results of
-   the statistics collector; they are described in <xref
-   linkend="monitoring-stats-views-table"/>.
+   There are some additional views that provide access to accumulated
+   statistics; they are described in
+   <xref linkend="monitoring-stats-views-table"/>.
   </para>
 
   <para>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -7885,15 +7885,15 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
    <sect1 id="runtime-config-statistics">
     <title>Run-time Statistics</title>
 
-    <sect2 id="runtime-config-statistics-collector">
-     <title>Query and Index Statistics Collector</title>
+    <sect2 id="runtime-config-cumulative-statistics">
+     <title>Cumulative Query and Index Statistics</title>
 
      <para>
-      These parameters control server-wide statistics collection features.
-      When statistics collection is enabled, the data that is produced can be
-      accessed via the <structname>pg_stat</structname> and
-      <structname>pg_statio</structname> family of system views.
-      Refer to <xref linkend="monitoring"/> for more information.
+      These parameters control the server-wide cumulative statistics system.
+      When enabled, the data that is collected can be accessed via the
+      <structname>pg_stat</structname> and <structname>pg_statio</structname>
+      family of system views.  Refer to <xref linkend="monitoring"/> for more
+      information.
      </para>
 
      <variablelist>
@@ -8031,22 +8031,37 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       </listitem>
      </varlistentry>
 
-     <varlistentry id="guc-stats-temp-directory" xreflabel="stats_temp_directory">
-      <term><varname>stats_temp_directory</varname> (<type>string</type>)
+     <varlistentry id="guc-stats-fetch-consistency" xreflabel="stats_fetch_consistency">
+      <term><varname>stats_fetch_consistency</varname> (<type>enum</type>)
       <indexterm>
-       <primary><varname>stats_temp_directory</varname> configuration parameter</primary>
+       <primary><varname>stats_fetch_consistency</varname> configuration parameter</primary>
       </indexterm>
       </term>
       <listitem>
        <para>
-        Sets the directory to store temporary statistics data in. This can be
-        a path relative to the data directory or an absolute path. The default
-        is <filename>pg_stat_tmp</filename>. Pointing this at a RAM-based
-        file system will decrease physical I/O requirements and can lead to
-        improved performance.
-        This parameter can only be set in the <filename>postgresql.conf</filename>
-        file or on the server command line.
+        Determines the behavior when cumulative statistics are accessed
+        multiple times within a transaction. When set to
+        <literal>none</literal>, each access re-fetches counters from shared
+        memory. When set to <literal>cache</literal>, the first access to
+        statistics for an object caches those statistics until the end of the
+        transaction unless <function>pg_stat_clear_snapshot()</function> is
+        called. When set to <literal>snapshot</literal>, the first statistics
+        access caches all statistics accessible in the current database, until
+        the end of the transaction unless
+        <function>pg_stat_clear_snapshot()</function> is called. The default
+        is <literal>cache</literal>.
        </para>
+       <note>
+        <para>
+         <literal>none</literal> is most suitable for monitoring systems. If
+         values are only accessed once, it is the most
+         efficient. <literal>cache</literal> ensures repeat accesses yield the
+         same values, which is important for queries involving
+         e.g. self-joins. <literal>snapshot</literal> can be useful when
+         interactively inspecting statistics, but has higher overhead,
+         particularly if many database objects exist.
+        </para>
+       </note>
       </listitem>
      </varlistentry>
 
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
@@ -28019,8 +28019,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
        <para>
         Requests to log the memory contexts of the backend with the
         specified process ID.  This function can send the request to
-        backends and auxiliary processes except logger and statistics
-        collector.  These memory contexts will be logged at
+        backends and auxiliary processes except logger.  These memory contexts
+        will be logged at
         <literal>LOG</literal> message level. They will appear in
         the server log based on the log configuration set
         (See <xref linkend="runtime-config-logging"/> for more information),
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
@@ -136,17 +136,16 @@
      The auxiliary processes consist of <!-- in alphabetical order -->
      <!-- NB: In the code, the autovac launcher doesn't use the auxiliary
           process scaffolding; however it does behave as one so we list it
-          here anyway. In addition, logger and stats collector aren't
-          connected to shared memory so most code outside postmaster.c
-          doesn't even consider them "procs" in the first place.
+          here anyway. In addition, logger isn't connected to shared memory so
+          most code outside postmaster.c doesn't even consider them "procs" in
+          the first place.
           -->
      the <glossterm linkend="glossary-autovacuum">autovacuum launcher</glossterm>
      (but not the autovacuum workers),
      the <glossterm linkend="glossary-background-writer">background writer</glossterm>,
      the <glossterm linkend="glossary-checkpointer">checkpointer</glossterm>,
      the <glossterm linkend="glossary-logger">logger</glossterm>,
      the <glossterm linkend="glossary-startup-process">startup process</glossterm>,
-     the <glossterm linkend="glossary-stats-collector">statistics collector</glossterm>,
      the <glossterm linkend="glossary-wal-archiver">WAL archiver</glossterm>,
      the <glossterm linkend="glossary-wal-receiver">WAL receiver</glossterm>
      (but not the <glossterm linkend="glossary-wal-sender">WAL senders</glossterm>),
@@ -434,6 +433,21 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-cumulative-statistics">
+   <glossterm>Cumulative Statistics System</glossterm>
+   <glossdef>
+    <para>
+     A system which, if enabled, accumulates statistical information
+     about the <glossterm linkend="glossary-instance">instance</glossterm>'s
+     activities.
+    </para>
+    <para>
+      For more information, see
+      <xref linkend="monitoring-stats"/>.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry>
    <glossterm>Data area</glossterm>
    <glosssee otherterm="glossary-data-directory" />
@@ -1563,22 +1577,6 @@
    </glossdef>
   </glossentry>
 
-  <glossentry id="glossary-stats-collector">
-   <glossterm>Stats collector (process)</glossterm>
-   <glossdef>
-    <para>
-     An <glossterm linkend="glossary-auxiliary-proc">auxiliary process</glossterm>
-     which, if enabled, receives statistical information
-     about the <glossterm linkend="glossary-instance">instance</glossterm>'s
-     activities.
-    </para>
-    <para>
-      For more information, see
-      <xref linkend="monitoring-stats"/>.
-    </para>
-   </glossdef>
-  </glossentry>
-
   <glossentry id="glossary-system-catalog">
    <glossterm>System catalog</glossterm>
    <glossdef>
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
@@ -2227,12 +2227,13 @@ HINT:  You can then restart the server after making the necessary configuration
    </para>
 
    <para>
-    The statistics collector is active during recovery. All scans, reads, blocks,
-    index usage, etc., will be recorded normally on the standby. Replayed
-    actions will not duplicate their effects on primary, so replaying an
-    insert will not increment the Inserts column of pg_stat_user_tables.
-    The stats file is deleted at the start of recovery, so stats from primary
-    and standby will differ; this is considered a feature, not a bug.
+    The cumulative statistics system is active during recovery. All scans,
+    reads, blocks, index usage, etc., will be recorded normally on the
+    standby. However, WAL replay will not increment relation and database
+    specific counters. I.e. replay will not increment pg_stat_all_tables
+    columns (like n_tup_ins), nor will reads or writes performed by the
+    startup process be tracked in the pg_statio views, nor will associated
+    pg_stat_database columns be incremented.
    </para>
 
    <para>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
@@ -839,7 +839,7 @@ vacuum insert threshold = vacuum base insert threshold + vacuum insert scale fac
     it may be beneficial to lower the table's
     <xref linkend="reloption-autovacuum-freeze-min-age"/> as this may allow
     tuples to be frozen by earlier vacuums.  The number of obsolete tuples and
-    the number of inserted tuples are obtained from the statistics collector;
+    the number of inserted tuples are obtained from the cumulative statistics system;
     it is a semi-accurate count updated by each <command>UPDATE</command>,
     <command>DELETE</command> and <command>INSERT</command> operation.  (It is
     only semi-accurate because some information might be lost under heavy
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
