From 6792d761ebf5e9261dab452130dcc2cd5ac48d0e Mon Sep 17 00:00:00 2001 From: Melanie Plageman Date: Mon, 9 Jan 2023 14:42:53 -0500 Subject: [PATCH v46 5/5] pg_stat_io documentation Author: Melanie Plageman Author: Samay Sharma Reviewed-by: Maciek Sakrejda Reviewed-by: Lukas Fittl Reviewed-by: Andres Freund Reviewed-by: Justin Pryzby Discussion: https://www.postgresql.org/message-id/flat/20200124195226.lth52iydq2n2uilq%40alap3.anarazel.de --- doc/src/sgml/monitoring.sgml | 318 +++++++++++++++++++++++++++++++++-- 1 file changed, 304 insertions(+), 14 deletions(-) diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 8d51ca3773..12246d46f4 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 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. @@ -3643,6 +3649,290 @@ 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, I/O context, and target I/O object 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 performed outside of shared + buffers 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: Permanent relations. + + + + + temp relation: Temporary relations. + + + + + + + + + + + read bigint + + + Number of read operations of op_bytes size. + + + + + + + + written bigint + + + Number of write operations of op_bytes size. + + + + + + + + extended bigint + + + Number of relation extend operations of op_bytes + size. + + + + + + + + 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 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. + + + + + + + + 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 the checkpointer. More information on configuring + 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. + More information on configuring the checkpointer can be found in . + + + + + -- 2.34.1