postgres.git / summary / log / commit / refs

commit    ea406250d9c77be9dc83f7d41662379319d1ffd5
Author:   Michael Paquier <michael@paquier.xyz>
Date:     Tue Apr 04 22:59:57 2023 +0000
First released in: 16.0, 11.20, 12.15, 13.11, 14.8, 15.3

    doc: Add more details about pg_stat_get_xact_blocks_{fetched,hit}
    
    The explanation describing the dependency to system read() calls for
    these two functions has been removed in ddfc2d9.  And after more
    discussion about d69c404, we have concluded that adding more details
    makes them easier to understand.
    
    While on it, use the term "block read requests" (maybe found in cache)
    rather than "buffers fetched" and "buffer hits".
    
    Per discussion with Melanie Plageman, Kyotaro Horiguchi, Bertrand
    Drouvot and myself.
    
    Discussion: https://postgr.es/m/CAAKRu_ZmdiScT4q83OAbfmR5AH-L5zWya3SXjaxiJvhCob-e2A@mail.gmail.com
    Backpatch-through: 11


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

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 194b63dddbf..cbc64c250d1 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -3147,8 +3147,11 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
       <entry><literal><function>pg_stat_get_xact_blocks_fetched</function>(oid)</literal><indexterm><primary>pg_stat_get_xact_blocks_fetched</primary></indexterm></entry>
       <entry><type>bigint</type></entry>
       <entry>
-       Returns the number of buffers fetched for table or index, in the current
-       transaction.
+       Returns the number of block read requests for table or index, in the
+       current transaction. This number minus
+       <function>pg_stat_get_xact_blocks_hit</function> gives the number of
+       kernel <function>read()</function> calls; the number of actual
+       physical reads is usually lower due to kernel-level buffering.
       </entry>
      </row>
 
@@ -3156,8 +3159,9 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
       <entry><literal><function>pg_stat_get_xact_blocks_hit</function>(oid)</literal><indexterm><primary>pg_stat_get_xact_blocks_hit</primary></indexterm></entry>
       <entry><type>bigint</type></entry>
       <entry>
-       Returns the number of buffer hits for table or index, in the current
-       transaction.
+       Returns the number of block read requests for table or index, in the
+       current transaction, found in cache (not triggering kernel
+       <function>read()</function> calls).
       </entry>
      </row>
 


[parent: e46a309bd8b2]