Subject: Re: Reconcile stats in find_tabstat_entry() and get rid of PgStat_BackendFunctionEntry

From: Kyotaro Horiguchi <[email-masked]>
Date: Tue, 28 Mar 2023 12:36:15 +0900 (JST)

At Tue, 28 Mar 2023 07:38:25 +0900, Michael Paquier <[email-masked]> wrote in 
> On Mon, Mar 27, 2023 at 10:24:46AM -0400, Melanie Plageman wrote:
> > I do like/prefer "block read requests" and
> > "blocks requested found in cache"
> > Though, now I fear my initial complaint may have been a bit pedantic.
> 
> That's fine.  Let's ask for extra opinions, then.
> 
> So, have others an opinion to share here?

I do not have a strong preference for the wording, but consistency is
important.  IMHO simply swapping out a few words won't really improve
things.

I found that commit ddfc2d9a37 removed the descriptions for
pg_stat_get_blocks_fetched and pg_stat_get_blocks_hit. Right before
that commit, monitoring.sgml had these lines:

-     <function>pg_stat_get_blocks_fetched</function> minus
-     <function>pg_stat_get_blocks_hit</function> gives the number of kernel
-     <function>read()</> calls issued for the table, index, or
-     database; the number of actual physical reads is usually
-     lower due to kernel-level buffering.  The <literal>*_blks_read</>
-     statistics columns use this subtraction, i.e., fetched minus hit.

The commit then added the following sentence to the description for
pg_statio_all_tables.heap_blks_read.

>     <entry>Number of disk blocks read from this table.
>     This value can also be returned by directly calling
>     the <function>pg_stat_get_blocks_fetched</function> and
>     <function>pg_stat_get_blocks_hit</function> functions and
>     subtracting the results.</entry>

Later, in 5f2b089387 it twas revised as:
+     <entry>Number of disk blocks read in this database</entry>

This revision lost the explantion regarding the relationship among
fetch, hit and read, as it became hidden in the views' definitions.

As the result, in the current state, it doesn't make sense to just add
a description for pg_stat_get_xact_blocks_fetched().

The confusion stems from the inconsistency between the views and
underlying functions related to block reads and hits. If we add
descriptions for the two functions, we should also explain their
relationship.  Otherwise, it might be better to add the functions
pg_stat_*_blocks_read() instead.

regards.

-- 
Kyotaro Horiguchi
NTT Open Source Software Center

---

From: Michael Paquier <[email-masked]>
Date: Tue, 28 Mar 2023 14:23:43 +0900

> +     <entry>Number of disk blocks read in this database</entry>

Yeah, maybe adding something like that at the bottom of the table for
stat functions, telling that the difference is the number of read()
calls, may help.  Perhaps also adding a mention that these are used in
none of the existing system views..

> pg_stat_*_blocks_read() instead.

I am not sure that we really need to get down to that as this holds
the same meaning as the current system views showing read as the
difference between fetched and hit.
--
Michael

---

From: "Drouvot, Bertrand" <[email-masked]>
Date: Tue, 28 Mar 2023 07:49:45 +0200

Hi,

On 3/28/23 7:23 AM, Michael Paquier wrote:
>> relationship. 

I agree that adding more explanation would help and avoid confusion.

What about something like?

for pg_stat_get_xact_blocks_fetched(): "block read requests for table or index, in the current
transaction. This number minus pg_stat_get_xact_blocks_hit() gives the number of kernel
read() calls."

pg_stat_get_xact_blocks_hit(): "block read requests for table or index, in the current
transaction, found in cache (not triggering kernel read() calls)".

Regards,

-- 
Bertrand Drouvot
PostgreSQL Contributors Team
RDS Open Source Databases
Amazon Web Services: https://aws.amazon.com

---

From: Michael Paquier <[email-masked]>
Date: Tue, 28 Mar 2023 15:16:36 +0900

> transaction, found in cache (not triggering kernel read() calls)".

Something among these lines within the table would be also OK by me.
Horiguchi-san or Melanie-san, perhaps you have counter-proposals?
--
Michael