From a2350adddce51f564a5f573b8b57f115bfd47ff4 Mon Sep 17 00:00:00 2001 From: Melanie Plageman Date: Mon, 9 Jan 2023 14:42:53 -0500 Subject: [PATCH v45 5/5] pg_stat_io documentation Author: Melanie Plageman Author: Samay Sharma Reviewed-by: Maciek Sakrejda Reviewed-by: Lukas Fittl Reviewed-by: Andres Freund Discussion: https://www.postgresql.org/message-id/flat/20200124195226.lth52iydq2n2uilq%40alap3.anarazel.de --- doc/src/sgml/monitoring.sgml | 321 +++++++++++++++++++++++++++++++++-- 1 file changed, 307 insertions(+), 14 deletions(-) diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 1691246e76..0f4d664516 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/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 per backend type, context, target object combination showing + 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,20 @@ 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 especially useful for + determining 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. @@ -3633,6 +3643,289 @@ 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 + backend type, I/O context, and target I/O object combination 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. + + + + <structname>pg_stat_io</structname> View + + + + + + Column Type + + + Description + + + + + + + + + backend_type text + + + Type of backend (e.g. background worker, autovacuum worker). See + 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_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 done outside of shared + buffers incurred while vacuuming and analyzing permanent relations. + + + + + bulkread: Qualifying large read I/O operations + done outside of shared buffers, for example, a sequential scan of a + large table. + + + + + bulkwrite: Qualifying large write I/O operations + done outside of shared buffers, such as COPY. + + + + + + + + + + io_object text + + + Target object of an I/O operation. Possible values are: + + + + relation: This includes permanent relations. + + + + + temp relation: This includes temporary relations. + + + + + + + + + + + read bigint + + + Number of read operations in units of op_bytes. + + + + + + + + written bigint + + + Number of write operations in units of op_bytes. + + + + + + + + extended bigint + + + Number of relation extend operations in units of + 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. + + + + + + + + evicted bigint + + + Number of times a block has been evicted from a shared or local buffer. + + + 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. + + + + + + + + reused 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. + + + + + + + + files_synced 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 in some + io_contexts and/or on some io_objects. + 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 in certain + io_contexts or on certain io_objects. + These cells will be NULL. For example, temporary tables are not + fsynced, so files_synced will be NULL + for io_object temp relation. Also, the + background writer does not perform reads, so read will be + NULL in rows for backend_type background + writer. + + + + pg_stat_io can be used to inform database tuning. + For example: + + + + A high evicted 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 files_synced by + client backends could indicate a misconfiguration of + shared buffers or of checkpointer. More information on checkpointer + configuration can be found in . + + + + + Normally, client backends should be able to rely on auxiliary processes + like the checkpointer and 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 checkpointer. More + information on checkpointer configuration can be found in . + + + + + -- 2.34.1