track_wal_io_timing

Definition PG 18 manual

Enables timing of WAL 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_io for the object wal and in the output of the pg_stat_get_backend_io() function for the object wal. Only superusers and users with the appropriate SET privilege can change this setting.

How it works

track_wal_io_timing measures wait time for WAL I/O and exposes it under the wal object in pg_stat_io and pg_stat_get_backend_io(). It is independent of ordinary database I/O timing.

Collection repeatedly reads the operating-system clock and can add platform-dependent overhead. pg_test_timing measures clock-read cost, while workload tests reveal aggregate impact.

It does not change wal_sync_method, durability, or WAL throughput. Pairing it with track_io_timing separates WAL waits from relation and temporary-file I/O. Its superuser context permits an authorized session change without a server restart.

Operational considerations

Expecting WAL timing to include relation and temporary-file I/O measured by track_io_timing.

Treating elapsed WAL waits as pure device service time.

Assuming the switch changes durability, wal_sync_method, or WAL throughput.

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

Workload guidance

OLAP: Read-heavy analytics may gain little from WAL timing, while bulk loads and refresh jobs can benefit substantially. Enable it for the write phases that use the evidence rather than because the workload is labeled OLAP.

OLTP: Enable it when WAL write and sync waits must be separated from relation I/O during commit-latency analysis. Measure platform clock overhead and correlate the counters with synchronous_commit, wal_sync_method, and storage behavior.

SMALL: Keep off unless WAL latency is an active diagnostic need and clock reads are inexpensive. Pair it with track_io_timing only when both WAL and non-WAL wait separation is useful.