Re: pg_stat_io_histogram

Hi Jakub,

Thank you for working on this. I tried the v15 series (the three patches on
the cfbot branch cf/6433, CF entry 6433) and would like to share what I saw.
I can send the scripts and the output if they are useful.

Setup
- Master at c1694b7b962c (11 Nov 2026) plus the three patches, applied as
one diff. `git apply --check` was clean, so no rebase is needed at the
moment.
- configure with --enable-cassert --enable-tap-tests --without-icu, on Linux
x86_64, gcc 15.2.
- The build finished with 0 compiler warnings.

Tests that passed
- `make check`: all 243 tests passed.
- src/test/recovery/t/029_stats_restart.pl (changed by the patch): ok, 46
tests.
- No errors or assertion failures in the server log of my first functional
run (checked before the restart step; I did not grep the other logs).

Functional test (track_io_timing = on, shared_buffers = 32MB, pgbench -i -s
5, then pgbench -c 4 -j 2 -T 10)
- The view has 7 columns and 6976 rows. Each row is one bucket, for example
[0,8), [8,16), ..., [131072,).
- Latencies look plausible to me. For example, about two thirds (4160 of
about 6300) of the client backend relation/normal reads were in the 8-32
us buckets. For checkpointer fsyncs, 31 of 54 were in 0.5-2 ms, with a
tail up to about 100 ms (152 ms total in pg_stat_io).
- With io_method=sync (autovacuum off, io_combine_limit=128kB, quiesced
server, one REPEATABLE READ snapshot), the histogram total equals the
pg_stat_io operation count for the relation-object read, write, extend and
fsync rows I compared. The WAL rows had no histogram samples, presumably
because track_wal_io_timing was at its default (off), and writeback
differs (see below).
- pg_stat_reset_shared('io') reset the histogram to 5 samples, which I
assume are the IO of my own queries.
- After a clean restart (pg_ctl stop -m fast, then start) the histogram
total was 3632, against 3572 before the stop. The values are kept; the
small difference is probably IO done during shutdown, but I did not check
that.

One thing I would like to ask about
- With io_method=worker, the histogram sample count for reads is higher than
the read count in pg_stat_io. In one run: vacuum reads 516 in pg_stat_io
against 1021 in the histogram; client backend bulkread 615 against 738;
background worker bulkread 575 against 659. My first run with the default
settings showed the same pattern (vacuum 516 against 931). With
io_method=sync the numbers were equal (516/516, 683/683, 678/678). Client
backend normal-context reads were nearly equal (549 against 551).
- I did not look for the cause. A guess is that some AIO reads are timed
more than once, or timed in a different place than they are counted, but
this is only a guess. Is it intended that one histogram sample is not
always one operation counted in pg_stat_io?
- Related: pgstat_count_io_op_time() adds one sample per call, while
pg_stat_io adds `cnt`. For writeback the histogram total was 18 against
565 operations (checkpointer, relation/normal). I did not check what `cnt`
the writeback caller passes, so this may be intended, but the
documentation could say what one sample means.

Not tested
- Overhead: I did not benchmark.
- Memory use: I did not measure shared or backend memory, so I cannot
comment on patches 0002 and 0003 beyond the tests above.
- WAL histograms (I did not enable track_wal_io_timing).
- Other workloads: only pgbench on relation objects, no temp tables, no
walsender or other backend types; only shared_buffers=32MB; one run per
configuration.
- make check-world, the isolation tests and the other TAP suites.
- Crash recovery, replicas, and pg_upgrade or the stats file format across
versions.
- Meson build, non-assert builds, Windows, 32-bit, other compilers, ICU
builds.
- io_method=io_uring, direct IO, and any platform other than Linux x86_64.
- The documentation build and wording. I read only a small part of the code
(mainly pgstat_count_io_op_time()), so this is not a code review; the
pg_bitutils.h changes were not reviewed.
- Concurrency stress and pgindent / code style.

Thanks again, and please let me know if you want me to rerun anything with
different settings.

Best regards,
Joao Rito