[RFC PATCH v1] Add EXPLAIN ANALYZE wait event reporting

Ilmar Y <tanswis42@gmail.com>

From: r314tive <tanswis42@gmail.com>
To: Michael Paquier <michael@paquier.xyz>
Cc: pgsql-hackers@postgresql.org
Date: 2026-05-14T11:19:45Z
Lists: pgsql-hackers

Attachments

Following Michael Paquier's note about PostgreSQL list practice, this v1
resends the same patch content as v0 as a single email with the patch series
attached.

No code changes from v0.

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

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, and regression coverage.
5. Harden accumulator handling with fixed-size, allocation-free storage.
6. Hide accumulator internals from public headers.
7. Keep psql EXPLAIN option completion current.

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.

Regards,
Ilmar