At Tue, 28 Mar 2023 07:38:25 +0900, Michael Paquier <michael@paquier.xyz> 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
