doc: Recommend pg_stat_io rather than pg_stat_wal in WAL configuration

michaelpq · michaelpq · commit 2f70871c2bc1 · 2025-02-20T13:55:00.000+09:00
Since a051e71, pg_stat_io is able to track statistics for the WAL activity, providing an equivalent of pg_stat_wal with more granularity for the fsyncs/writes counts and timings, as the data is split across backend types. This commit now recommends pg_stat_io rather than pg_stat_wal in the section "WAL configuration", some of the latter's attributes being candidate for removal in a follow-up commit. Extracted from a larger patch by the same author. Author: Bertrand Drouvot <bertranddrouvot.pg@gmail.com> Discussion: https://postgr.es/m/Z7RkQ0EfYaqqjgz/@ip-10-97-1-34.eu-west-3.compute.internal
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
@@ -810,11 +810,12 @@
   <para>
    There are two internal functions to write WAL data to disk:
    <function>XLogWrite</function> and <function>issue_xlog_fsync</function>.
-   When <xref linkend="guc-track-wal-io-timing"/> is enabled, the total
+   When <xref linkend="guc-track-io-timing"/> is enabled, the total
    amounts of time <function>XLogWrite</function> writes and
    <function>issue_xlog_fsync</function> syncs WAL data to disk are counted as
-   <literal>wal_write_time</literal> and <literal>wal_sync_time</literal> in
-   <xref linkend="pg-stat-wal-view"/>, respectively.
+   <varname>write_time</varname> and <varname>sync_time</varname> in
+   <xref linkend="pg-stat-io-view"/> for the <varname>object</varname>
+   <literal>wal</literal>, respectively.
    <function>XLogWrite</function> is normally called by
    <function>XLogInsertRecord</function> (when there is no space for the new
    record in WAL buffers), <function>XLogFlush</function> and the WAL writer,
@@ -829,11 +830,12 @@
    <literal>fsync</literal>, or <literal>fsync_writethrough</literal>,
    the write operation moves WAL buffers to kernel cache and
    <function>issue_xlog_fsync</function> syncs them to disk. Regardless
-   of the setting of <varname>track_wal_io_timing</varname>, the number
+   of the setting of <varname>track_io_timing</varname>, the number
    of times <function>XLogWrite</function> writes and
    <function>issue_xlog_fsync</function> syncs WAL data to disk are also
-   counted as <literal>wal_write</literal> and <literal>wal_sync</literal>
-   in <structname>pg_stat_wal</structname>, respectively.
+   counted as <varname>writes</varname> and <varname>fsyncs</varname>
+   in <structname>pg_stat_io</structname> for the <varname>object</varname>
+   <literal>wal</literal>, respectively.
   </para>
 
   <para>
