Re: monitoring-stats.html documentation - Mailing list pgsql-hackers

Robert Haas wrote:
> On Sat, Apr 4, 2009 at 6:08 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > Robert Haas <robertmhaas@gmail.com> writes:
> >> http://developer.postgresql.org/pgdocs/postgres/monitoring-stats.html
> >> says: "Note: blocks_fetched minus blocks_hit gives the number of
> >> kernel read() calls issued for the table, index, or database; but the
> >> actual number of physical reads is usually lower due to kernel-level
> >> buffering." ?This seems to imply that anything that increases
> >> blocks_hit should also increase blocks_fetched, but that doesn't seem
> >> to match the actual behavior.
> >
> >> rhaas=# select heap_blks_read, heap_blks_hit from pg_statio_user_tables;
> >
> > It's talking about the underlying pg_stat_get_db_blocks_fetched()
> > function, not heap_blks_read which is just a view field defined as
> >
> > ? ? ? ? ? ?pg_stat_get_blocks_fetched(C.oid) -
> > ? ? ? ? ? ? ? ? ? ?pg_stat_get_blocks_hit(C.oid) AS heap_blks_read,
> >
> > Probably that sentence ought to spell out the full function name
> > instead of abbreviating.
>
> Oh, I see.  I misread it, but I agree it could be written in a way
> that would make it less likely to be misread.  You could even add a
> sentence explicitly mentioning that the views display the difference
> of the two values.

Done with attached patch;  good idea.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/monitoring.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v
retrieving revision 1.67
diff -c -c -r1.67 monitoring.sgml
*** doc/src/sgml/monitoring.sgml    9 Apr 2009 22:32:02 -0000    1.67
--- doc/src/sgml/monitoring.sgml    10 Apr 2009 03:12:00 -0000
***************
*** 927,934 ****
       <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; but the actual number of physical reads is usually
!      lower due to kernel-level buffering.
      </para>
     </note>

--- 927,935 ----
       <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 uses this subtraction, i.e. fetched minus hit.
      </para>
     </note>