document? Re: Do I understand commit timestamps correctly?

On 03/23/18 11:29, Chapman Flack wrote:
> Can somebody confirm or correct what I (think I)'ve gleaned from
> the code?
> ...
> - The extra machinery turned on by track_commit_timestamp maintains
> a cache of recent ones so they can be efficiently queried from SQL
> in normal operation.

I guess the depth of this cache is determined by the setting of
autovacuum_freeze_max_age. This is covered (including arithmetic
for sizing the cache) in a paragraph part-way down the
vacuum-for-wraparound sect2 in the maintenance chapter.

It isn't mentioned at the description of track_commit_timestamp,
pg_xact_commit_timestamp(), or autovacuum_freeze_max_age.

Should it be?

A minimalist doc addition could be to add a link from the description
of track_commit_timestamp to that of autovacuum_freeze_max_age.

-> The autovacuum_freeze_max_age description already has a link
to the maintenance section (but could stand a few words added saying
it also matters for commit timestamps).

The description for pg_xact_commit_timestamp() and pg_last_committed_xact()
already has a link to track_commit_timestamp (and as that defaults to off,
anyone interested in the functionality likely to follow the link, so the
trail of breadcrumbs would be complete). The language "only for transactions
that were committed after it was enabled" could perhaps also say "and
have not yet been frozen".

I could send a patch if this seems worth documenting.

Regards,
-Chap