Add pg_stat_io view, providing more detailed IO statistics

Builds on 28e626b and f30d62c. See the former for motivation.

Rows of the view show IO operations for a particular backend type, IO target
object, IO context combination (e.g. a client backend's operations on
permanent relations in shared buffers) and each column in the view is the
total number of IO Operations done (e.g. writes). So a cell in the view would
be, for example, the number of blocks of relation data written from shared
buffers by client backends since the last stats reset.

In anticipation of tracking WAL IO and non-block-oriented IO (such as
temporary file IO), the "op_bytes" column specifies the unit of the "reads",
"writes", and "extends" columns for a given row.

Rows for combinations of IO operation, backend type, target object and context
that never occur, are ommitted entirely. For example, checkpointer will never
operate on temporary relations.

Similarly, if an IO operation never occurs for such a combination, the IO
operation's cell will be null, to distinguish from 0 observed IO
operations. For example, bgwriter should not perform reads.

Note that some of the cells in the view are redundant with fields in
pg_stat_bgwriter (e.g. buffers_backend). For now, these have been kept for
backwards compatibility.

Bumps catversion.

Author: Melanie Plageman 
Author: Samay Sharma 
Reviewed-by: Maciek Sakrejda 
Reviewed-by: Lukas Fittl 
Reviewed-by: Andres Freund 
Reviewed-by: Justin Pryzby 
Discussion: https://postgr.es/m/[email protected]

Author: anarazel

doc/src/sgml/monitoring.sgml

@@ -469,6 +469,16 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
       
      
 
+     
+      pg_stat_iopg_stat_io
+      
+       One row for each combination of backend type, context, and target object
+       containing cluster-wide I/O statistics.
+       See 
+       pg_stat_io for details.
+     
+     
+
      
       pg_stat_replication_slotspg_stat_replication_slots
       One row per replication slot, showing statistics about the
@@ -665,20 +675,16 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
   
 
   
-   The pg_statio_ views are primarily useful to
-   determine the effectiveness of the buffer cache.  When the number
-   of actual disk reads is much smaller than the number of buffer
-   hits, then the cache is satisfying most read requests without
-   invoking a kernel call. However, these statistics do not give the
-   entire story: due to the way in which PostgreSQL
-   handles disk I/O, data that is not in the
-   PostgreSQL buffer cache might still reside in the
-   kernel's I/O cache, and might therefore still be fetched without
-   requiring a physical read. Users interested in obtaining more
-   detailed information on PostgreSQL I/O behavior are
-   advised to use the PostgreSQL statistics views
-   in combination with operating system utilities that allow insight
-   into the kernel's handling of I/O.
+   The pg_stat_io and
+   pg_statio_ set of views are useful for determining
+   the effectiveness of the buffer cache. They can be used to calculate a cache
+   hit ratio. Note that while PostgreSQL's I/O
+   statistics capture most instances in which the kernel was invoked in order
+   to perform I/O, they do not differentiate between data which had to be
+   fetched from disk and that which already resided in the kernel page cache.
+   Users are advised to use the PostgreSQL
+   statistics views in combination with operating system utilities for a more
+   complete picture of their database's I/O performance.
   
 
  
@@ -3669,6 +3675,293 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
     last_archived_wal have also been successfully
     archived.
   
+ 
+
+ 
+  <structname>pg_stat_io</structname>
+
+  
+   pg_stat_io
+  
+
+  
+   The pg_stat_io view will contain one row for each
+   combination of backend type, target I/O object, and I/O context, showing
+   cluster-wide I/O statistics. Combinations which do not make sense are
+   omitted.
+  
+
+  
+   Currently, I/O on relations (e.g. tables, indexes) is tracked. However,
+   relation I/O which bypasses shared buffers (e.g. when moving a table from one
+   tablespace to another) is currently not tracked.
+  
+
+  3701+   <structname>pg_stat_io</structname> View3702+   3703+    3704+     3705+      3706+       3707+        Column Type3708+       3709+       3710+        Description3711+       3712+      3713+     3714+    3715+    3716+     3717+      3718+       3719+        backend_type text3720+       3721+       3722+        Type of backend (e.g. background worker, autovacuum worker). See 3723+        linkend="monitoring-pg-stat-activity-view">3724+        pg_stat_activity for more information3725+        on backend_types. Some3726+        backend_types do not accumulate I/O operation3727+        statistics and will not be included in the view.3728+       3729+      3730+     3731+3732+     3733+      3734+       3735+        io_object text3736+       3737+       3738+        Target object of an I/O operation. Possible values are:3739+       3740+        3741+         3742+          relation: Permanent relations.3743+         3744+        3745+        3746+         3747+          temp relation: Temporary relations.3748+         3749+        3750+       3751+       3752+      3753+     3754+3755+     3756+      3757+       3758+        io_context text3759+       3760+       3761+        The context of an I/O operation. Possible values are:3762+       3763+       3764+        3765+         3766+          normal: The default or standard3767+          io_context for a type of I/O operation. For3768+          example, by default, relation data is read into and written out from3769+          shared buffers. Thus, reads and writes of relation data to and from3770+          shared buffers are tracked in io_context3771+          normal.3772+         3773+        3774+        3775+         3776+          vacuum: I/O operations performed outside of shared3777+          buffers while vacuuming and analyzing permanent relations. Temporary3778+          table vacuums use the same local buffer pool as other temporary table3779+          IO operations and are tracked in io_context3780+          normal.3781+         3782+        3783+        3784+         3785+          bulkread: Certain large read I/O operations3786+          done outside of shared buffers, for example, a sequential scan of a3787+          large table.3788+         3789+        3790+        3791+         3792+          bulkwrite: Certain large write I/O operations3793+          done outside of shared buffers, such as COPY.3794+         3795+        3796+       3797+      3798+     3799+3800+     3801+      3802+       3803+        reads bigint3804+       3805+       3806+        Number of read operations, each of the size specified in3807+        op_bytes.3808+       3809+      3810+     3811+3812+     3813+      3814+       3815+        writes bigint3816+       3817+       3818+        Number of write operations, each of the size specified in3819+        op_bytes.3820+       3821+      3822+     3823+3824+     3825+      3826+       3827+        extends bigint3828+       3829+       3830+        Number of relation extend operations, each of the size specified in3831+        op_bytes.3832+       3833+      3834+     3835+3836+     3837+      3838+       3839+        op_bytes bigint3840+       3841+       3842+        The number of bytes per unit of I/O read, written, or extended.3843+       3844+       3845+        Relation data reads, writes, and extends are done in3846+        block_size units, derived from the build-time3847+        parameter BLCKSZ, which is 8192 by3848+        default.3849+       3850+      3851+     3852+3853+     3854+      3855+       3856+        evictions bigint3857+       3858+       3859+        Number of times a block has been written out from a shared or local3860+        buffer in order to make it available for another use.3861+       3862+       3863+        In io_context normal, this counts3864+        the number of times a block was evicted from a buffer and replaced with3865+        another block. In io_contexts3866+        bulkwrite, bulkread, and3867+        vacuum, this counts the number of times a block was3868+        evicted from shared buffers in order to add the shared buffer to a3869+        separate, size-limited ring buffer for use in a bulk I/O operation.3870+        3871+      3872+     3873+3874+     3875+      3876+       3877+        reuses bigint3878+       3879+       3880+        The number of times an existing buffer in a size-limited ring buffer3881+        outside of shared buffers was reused as part of an I/O operation in the3882+        bulkread, bulkwrite, or3883+        vacuum io_contexts.3884+       3885+      3886+     3887+3888+     3889+      3890+       3891+        fsyncs bigint3892+       3893+       3894+        Number of fsync calls. These are only tracked in3895+        io_context normal.3896+       3897+      3898+     3899+3900+     3901+      3902+       3903+        stats_reset timestamp with time zone3904+       3905+       3906+        Time at which these statistics were last reset.3907+       3908+      3909+     3910+    3911+   3912+  
+   <structname>pg_stat_io</structname> View
+   
+    
+     
+      
+       
+        Column Type
+       
+       
+        Description
+       
+      
+     
+    
+    
+     
+      
+       
+        backend_type text
+       
+       
+
+        linkend="monitoring-pg-stat-activity-view">
+        pg_stat_activity for more information
+        on backend_types. Some
+        backend_types do not accumulate I/O operation
+        statistics and will not be included in the view.
+       
+      
+     
+
+     
+      
+       
+        io_object text
+       
+       
+        Target object of an I/O operation. Possible values are:
+       
+        
+         
+          relation: Permanent relations.
+         
+        
+        
+         
+          temp relation: Temporary relations.
+         
+        
+       
+       
+      
+     
+
+     
+      
+       
+        io_context text
+       
+       
+        The context of an I/O operation. Possible values are:
+       
+       
+        
+         
+          normal: The default or standard
+          io_context for a type of I/O operation. For
+          example, by default, relation data is read into and written out from
+          shared buffers. Thus, reads and writes of relation data to and from
+          shared buffers are tracked in io_context
+          normal.
+         
+        
+        
+         
+          vacuum: I/O operations performed outside of shared
+          buffers while vacuuming and analyzing permanent relations. Temporary
+          table vacuums use the same local buffer pool as other temporary table
+          IO operations and are tracked in io_context
+          normal.
+         
+        
+        
+         
+          bulkread: Certain large read I/O operations
+          done outside of shared buffers, for example, a sequential scan of a
+          large table.
+         
+        
+        
+         
+          bulkwrite: Certain large write I/O operations
+          done outside of shared buffers, such as COPY.
+         
+        
+       
+      
+     
+
+     
+      
+       
+        reads bigint
+       
+       
+        Number of read operations, each of the size specified in
+        op_bytes.
+       
+      
+     
+
+     
+      
+       
+        writes bigint
+       
+       
+        Number of write operations, each of the size specified in
+        op_bytes.
+       
+      
+     
+
+     
+      
+       
+        extends bigint
+       
+       
+        Number of relation extend operations, each of the size specified in
+        op_bytes.
+       
+      
+     
+
+     
+      
+       
+        op_bytes bigint
+       
+       
+        The number of bytes per unit of I/O read, written, or extended.
+       
+       
+        Relation data reads, writes, and extends are done in
+        block_size units, derived from the build-time
+        parameter BLCKSZ, which is 8192 by
+        default.
+       
+      
+     
+
+     
+      
+       
+        evictions bigint
+       
+       
+        Number of times a block has been written out from a shared or local
+        buffer in order to make it available for another use.
+       
+       
+        In io_context normal, this counts
+        the number of times a block was evicted from a buffer and replaced with
+        another block. In io_contexts
+        bulkwrite, bulkread, and
+        vacuum, this counts the number of times a block was
+        evicted from shared buffers in order to add the shared buffer to a
+        separate, size-limited ring buffer for use in a bulk I/O operation.
+        
+      
+     
+
+     
+      
+       
+        reuses bigint
+       
+       
+        The number of times an existing buffer in a size-limited ring buffer
+        outside of shared buffers was reused as part of an I/O operation in the
+        bulkread, bulkwrite, or
+        vacuum io_contexts.
+       
+      
+     
+
+     
+      
+       
+        fsyncs bigint
+       
+       
+        Number of fsync calls. These are only tracked in
+        io_context normal.
+       
+      
+     
+
+     
+      
+       
+        stats_reset timestamp with time zone
+       
+       
+        Time at which these statistics were last reset.
+       
+      
+     
+    
+   
+  
+
+  
+   Some backend types never perform I/O operations on some I/O objects and/or
+   in some I/O contexts. These rows are omitted from the view. For example, the
+   checkpointer does not checkpoint temporary tables, so there will be no rows
+   for backend_type checkpointer and
+   io_object temp relation.
+  
+
+  
+   In addition, some I/O operations will never be performed either by certain
+   backend types or on certain I/O objects and/or in certain I/O contexts.
+   These cells will be NULL. For example, temporary tables are not
+   fsynced, so fsyncs will be NULL for
+   io_object temp relation. Also, the
+   background writer does not perform reads, so reads will
+   be NULL in rows for backend_type background
+   writer.
+  
+
+  
+   pg_stat_io can be used to inform database tuning.
+   For example:
+   
+    
+     
+      A high evictions count can indicate that shared
+      buffers should be increased.
+     
+    
+    
+     
+      Client backends rely on the checkpointer to ensure data is persisted to
+      permanent storage. Large numbers of fsyncs by
+      client backends could indicate a misconfiguration of
+      shared buffers or of the checkpointer. More information on configuring
+      the checkpointer can be found in .
+     
+    
+    
+     
+      Normally, client backends should be able to rely on auxiliary processes
+      like the checkpointer and the background writer to write out dirty data
+      as much as possible. Large numbers of writes by client backends could
+      indicate a misconfiguration of shared buffers or of the checkpointer.
+
+      linkend="wal-configuration"/>.
+     
+    
+   
+  
+
 
  
 

src/backend/catalog/system_views.sql

@@ -1117,6 +1117,21 @@ CREATE VIEW pg_stat_bgwriter AS
         pg_stat_get_buf_alloc() AS buffers_alloc,
         pg_stat_get_bgwriter_stat_reset_time() AS stats_reset;
 
+CREATE VIEW pg_stat_io AS
+SELECT
+       b.backend_type,
+       b.io_object,
+       b.io_context,
+       b.reads,
+       b.writes,
+       b.extends,
+       b.op_bytes,
+       b.evictions,
+       b.reuses,
+       b.fsyncs,
+       b.stats_reset
+FROM pg_stat_get_io() b;
+
 CREATE VIEW pg_stat_wal AS
     SELECT
         w.wal_records,