# 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 {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `bool` | Upstream pg_settings type |
| Context | `superuser` | Settable at runtime by a superuser |
| Unit | — | Raw unit |
| Range | — | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Statistics / Cumulative Query and Index Statistics | Upstream classification |
| Latest boot value | `off` | off |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG9.2 |
| Present in | PG9.2–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`309c64745ea1`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=309c64745ea145d7c731e1fe610631b2b84e7e88) — Rename track_iotiming GUC to track_io_timing. |
| Commit date | 2012-04-29 |
| Discussion | — |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG9.2–19 Beta 3 | `off` | — | off |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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 {#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. |
{.full-width}

## Pigsty {#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'` |
{.full-width}

> [!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 {#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.

## Related parameters {#related-parameters}

[`track_wal_io_timing`](/parameters/track-wal-io-timing/) · [`track_counts`](/parameters/track-counts/) · [`stats_fetch_consistency`](/parameters/stats-fetch-consistency/) · [`effective_io_concurrency`](/parameters/effective-io-concurrency/) · [`compute_query_id`](/parameters/compute-query-id/)

## References {#references}

- [PostgreSQL 19 Beta 3 — track_io_timing](https://www.postgresql.org/docs/19/runtime-config-statistics.html#GUC-TRACK-IO-TIMING)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)