From ef053ae1c40546449d1e77fdd48e0d689a9e41d4 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sun, 19 Mar 2023 18:45:58 -0500
Subject: [PATCH 2/4] WIP: v16 docs: Add pg_stat_io view, providing more
 detailed IO statistics

a9c70b46dbe152e094f137f7e6ba9cd3a638ee25
---
 doc/src/sgml/monitoring.sgml | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index a37331ec524..201408bf20a 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -679,9 +679,9 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
    <structname>pg_statio_</structname> set of views are useful for determining
    the effectiveness of the buffer cache. They can be used to calculate a cache
    hit ratio. Note that while <productname>PostgreSQL</productname>'s I/O
-   statistics capture most instances in which the kernel was invoked in order
-   to perform I/O, they do not differentiate between data which had to be
-   fetched from disk and that which already resided in the kernel page cache.
+   statistics capture most instances which required a system call in order
+   to perform I/O, they do not differentiate between data which was already
+   present in the kernel page cache and that which had to be fetched from disk.
    Users are advised to use the <productname>PostgreSQL</productname>
    statistics views in combination with operating system utilities for a more
    complete picture of their database's I/O performance.
@@ -3770,8 +3770,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
          <para>
           <literal>normal</literal>: The default or standard
           <varname>io_context</varname> for a type of I/O operation. For
-          example, by default, relation data is read into and written out from
-          shared buffers. Thus, reads and writes of relation data to and from
+          example, relation data is read into and written out from
+          a general pool of shared buffers. Thus, reads and writes of relation data to and from
           shared buffers are tracked in <varname>io_context</varname>
           <literal>normal</literal>.
          </para>
@@ -3781,14 +3781,14 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
           <literal>vacuum</literal>: I/O operations performed outside of shared
           buffers while vacuuming and analyzing permanent relations. Temporary
           table vacuums use the same local buffer pool as other temporary table
-          IO operations and are tracked in <varname>io_context</varname>
+          I/O operations and are tracked in <varname>io_context</varname>
           <literal>normal</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>bulkread</literal>: Certain large read I/O operations
-          done outside of shared buffers, for example, a sequential scan of a
+          done in a ring buffer of limited size of shared buffers, for example, a sequential scan of a
           large table.
          </para>
         </listitem>
@@ -3979,7 +3979,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
    Some backend types never perform I/O operations on some I/O objects and/or
    in some I/O contexts. These rows are omitted from the view. For example, the
    checkpointer does not checkpoint temporary tables, so there will be no rows
-   for <varname>backend_type</varname> <literal>checkpointer</literal> and
+   with <varname>backend_type</varname> <literal>checkpointer</literal> and
    <varname>io_object</varname> <literal>temp relation</literal>.
   </para>
 
-- 
2.34.1