Re: Add explanations which are influenced by track_io_timing

[Fujii Masao]

On 2020/05/13 21:54, Atsushi Torikoshi wrote:

Hi,

When track_io_timing is on, I/O timing information is
displayed in pg_stat_database, in the output of EXPLAIN
when the BUFFERS option is used, and in pg_stat_statements
as documented in [1].

This is also described in the manual for pg_stat_statements
[2], however, manuals for pg_stat_database and EXPLAIN
doesn't refer to it.

I think it'll be better to add descriptions to both of them
for consistency.

Thoughts?

+1

+      in milliseconds(if <xref linkend="guc-track-io-timing"/> is enabled,
+      otherwise zero)

It's better to add a space character just after "seconds".

-      written.
+      written. In addition, If <xref linkend="guc-track-io-timing"/> is 
enabled,
+      also include I/O Timings.

Isn't it better to just use clearer description like "the time reading and
writing data blocks" here instead of "I/O Timing"?
What about the attached patch based on yours?

Regards,

--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 579ccd34d4..791f371d9d 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -2706,13 +2706,17 @@ SELECT pid, wait_event_type, wait_event FROM 
pg_stat_activity WHERE wait_event i
      <entry><structfield>blk_read_time</structfield></entry>
      <entry><type>double precision</type></entry>
      <entry>Time spent reading data file blocks by backends in this database,
-      in milliseconds</entry>
+      in milliseconds (if <xref linkend="guc-track-io-timing"/> is enabled,
+      otherwise zero)
+     </entry>
     </row>
     <row>
      <entry><structfield>blk_write_time</structfield></entry>
      <entry><type>double precision</type></entry>
      <entry>Time spent writing data file blocks by backends in this database,
-      in milliseconds</entry>
+      in milliseconds (if <xref linkend="guc-track-io-timing"/> is enabled,
+      otherwise zero)
+     </entry>
     </row>
     <row>
      <entry><structfield>stats_reset</structfield></entry>
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index c6f333c3c9..292c655b6b 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -171,8 +171,9 @@ ROLLBACK;
      <para>
       Include information on buffer usage. Specifically, include the number of
       shared blocks hit, read, dirtied, and written, the number of local blocks
-      hit, read, dirtied, and written, and the number of temp blocks read and
-      written.
+      hit, read, dirtied, and written, the number of temp blocks read and
+      written, and the time spent reading and writing data file blocks
+      (in milliseconds) if <xref linkend="guc-track-io-timing"/> is enabled.
       A <emphasis>hit</emphasis> means that a read was avoided because the 
block was
       found already in cache when needed.
       Shared blocks contain data from regular tables and indexes;