Hi,
On 3/28/23 7:23 AM, Michael Paquier wrote:
> On Tue, Mar 28, 2023 at 12:36:15PM +0900, Kyotaro Horiguchi wrote:
>> 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.
>>
>> Later, in 5f2b089387 it twas revised as:
>> + <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..
>
>> 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.
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
