# track_wal_io_timing

> track_wal_io_timing — Collects timing statistics for WAL I/O activity. Observed in PG14–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 WAL 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 | PG14 |
| Present in | PG14–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`ff99918c625a`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=ff99918c625a84c91e7391db9032112ec8653623) — Track total amounts of times spent writing and syncing WAL data to disk. |
| Commit date | 2021-03-09 |
| Discussion | [thread 1](https://postgr.es/m/0509ad67b585a5b86a83d445dfa75392@oss.nttdata.com) |

## Default history {#default-history}

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

## How it works {#mechanism}

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.

## Tuning advice {#tuning-advice}

> [!TIP]
> **Advice.** These are workload-specific starting points and must be validated with measurements.

| Workload | Guidance |
| --- | --- |
| 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. |
| 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. |
| Small nodes | 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. |
{.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 | Unmodified | — | — |
| OLAP | Unmodified | — | — |
| CRIT | Unmodified | — | — |
| TINY | Unmodified | — | — |
{.full-width}

> [!CAUTION]
> **Advice — pending human review.** Fact from the current Pigsty template projection: OLTP: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

## Common pitfalls {#common-pitfalls}

- 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.

## Related parameters {#related-parameters}

[`track_io_timing`](/parameters/track-io-timing/) · [`wal_sync_method`](/parameters/wal-sync-method/) · [`synchronous_commit`](/parameters/synchronous-commit/) · [`track_counts`](/parameters/track-counts/) · [`stats_fetch_consistency`](/parameters/stats-fetch-consistency/)

## References {#references}

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