track_io_timing

track_io_timing — Collects timing statistics for database I/O activity. Observed in PG9.2–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Collects timing statistics for database I/O activity.”

Identity

Type , Valuebool: Upstream pg_settings type
Context , Valuesuperuser: Settable at runtime by a superuser
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueStatistics / Cumulative Query and Index Statistics: Upstream classification
Latest boot value , Valueoff: off

Lifecycle

Fact	Value
First observed	PG9.2
Present in	PG9.2–19 Beta 3
Removed in	No
Introduction commit	`309c64745ea1` — Rename track_iotiming GUC to track_io_timing.
Commit date	2012-04-29
Discussion	—

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG9.2–19 Beta 3	`off`	—	off

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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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; Pigsty’s on value is an observability choice, not a throughput tuning value.
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.
Small nodes	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.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	`on`	different	`'on'`
OLAP	`on`	different	`'on'`
CRIT	`on`	different	`'on'`
TINY	`on`	different	`'on'`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.2–19 Beta 3 = on (dcs); OLAP: PG9.2–19 Beta 3 = on (dcs); CRIT: PG9.2–19 Beta 3 = on (dcs); TINY: PG9.2–19 Beta 3 = on (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The explicit on setting follows the source comment’s goal of collecting I/O statistics across all profiles, accepting platform-dependent clock overhead.

Common pitfalls

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.

track_wal_io_timing · track_counts · stats_fetch_consistency · effective_io_concurrency · compute_query_id