Thread

[RFC PATCH v3] Add EXPLAIN ANALYZE wait event reporting

Ilmar Y <tanswis42@gmail.com> — 2026-05-28T11:21:32Z

This v3 rebases v2 over current master after CFBot reported that v2 no
longer applied cleanly.

The rebase conflict was in psql EXPLAIN option completion. Current master
already has IO in that completion list; v3 preserves IO and adds WAITS
alongside it.

No accounting-code changes from v2.

One mechanical difference from v2: the old v2 patch that only kept psql
completion current is gone.  That change is obsolete on current master, so
v3 has seven patches instead of eight.

v0 thread:
https://www.postgresql.org/message-id/cover.1778280923.git.tanswis42%40gmail.com

CommitFest entry:
https://commitfest.postgresql.org/patch/6753/

This RFC prototype adds EXPLAIN (ANALYZE, WAITS), which reports completed
wait
intervals observed through pgstat_report_wait_start/end().

Statement-level wait events are counted once per active statement collector.
Plan-node wait events use inclusive attribution, similar to EXPLAIN ANALYZE
timing: a completed wait is attributed to every active plan node captured
when
the wait begins.  Per-node wait times therefore must not be summed across
plan
nodes.

The patch series is split as follows:

1. Add statement-level EXPLAIN WAITS reporting.
2. Aggregate statement-level EXPLAIN WAITS from parallel workers.
3. Attribute EXPLAIN WAITS to plan nodes.
4. Refine attribution semantics, documentation, regression coverage, and
psql
   EXPLAIN option completion for current master.
5. Harden accumulator handling with fixed-size, allocation-free storage.
6. Hide accumulator internals from public headers.
7. Stabilize EXPLAIN WAITS regression tests.

The main review questions are:

- whether the option should be named WAITS or WAIT_EVENTS;
- whether inclusive per-node attribution is the right initial semantics;
- whether the fixed accumulator limit and overflow reporting are acceptable;
- whether the disabled/enabled hot-path overhead is acceptable.

Local verification for this rebase:

- the v3 patch series applies cleanly to current origin/master;
- git diff --check passes;
- a fresh verify worktree after applying the v3 attachments matches the v3
  branch tree.

I did not rerun the regression suite in the fresh v3 rebase worktree; it is
not configured for a local build. The v2 accounting code plus the regression
stabilization patch passed make -C src/test/regress check TESTS=explain
locally before this rebase.

Regards,
Ilmar

>