track_io_timing

Definition PG 18 manual

Enables timing of database I/O waits. This parameter is off by default, as it will repeatedly query the operating system for the current time, which may cause significant overhead on some platforms. You can use the pg_test_timing tool to measure the overhead of timing on your system. I/O timing information is displayed in pg_stat_database, pg_stat_io (if object is not wal), in the output of the pg_stat_get_backend_io() function (if object is not wal), in the output of EXPLAIN when the BUFFERS option is used, in the output of VACUUM when the VERBOSE option is used, by autovacuum for auto-vacuums and auto-analyzes, when log_autovacuum_min_duration is set and by pg_stat_statements. Only superusers and users with the appropriate SET privilege can change this setting.

How it works

track_io_timing measures database I/O wait time outside the WAL object. It populates pg_stat_database, pg_stat_io, pg_stat_get_backend_io(), EXPLAIN with BUFFERS, maintenance output, and supporting extensions.

The setting repeatedly reads the operating-system clock; overhead is platform dependent and measurable with pg_test_timing. It records elapsed wait, not device service time in isolation.

WAL I/O timing is controlled separately by track_wal_io_timing. Enabling timing adds observability but does not make I/O asynchronous or change planner costs. Its superuser context permits an authorized session change without a server restart.

Operational considerations

Treating measured wait time as isolated device service time without queueing or scheduling effects.

Expecting the switch to make I/O asynchronous or change planner cost estimates.

Assuming it includes WAL timing, which is controlled by track_wal_io_timing.

Enabling it without measuring clock-read overhead on the actual platform.

Workload guidance

OLAP: Long scans and spills make relation and temporary-file timing valuable. Keep it on when those counters drive diagnosis, but compare execution overhead and distinguish elapsed waits from device-only service time.

OLTP: Enable it when database I/O wait time is needed for pg_stat_io, EXPLAIN with BUFFERS, or incident analysis. Measure clock-read overhead with pg_test_timing and at peak statement rates;

SMALL: Use on only when the platform's clock-read cost is acceptable and the measurements are consumed. The boolean has no conservative numeric size; off removes timing but does not remove I/O itself.