Re: doc: New cumulative stats subsystem obsoletes comment in maintenance.sgml

On Fri, Aug 12, 2022 at 12:48 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Mon, Jul 18, 2022 at 08:04:12PM -0700, Andres Freund wrote:
> > Hi,
> >
> > On 2022-07-18 19:47:39 -0700, David G. Johnston wrote:
> > > On Thu, Jul 14, 2022 at 4:31 PM Andres Freund <andres(at)anarazel(dot)de>
> wrote:
> > > > It might make sense to still say semi-accurate, but adjust the
> explanation
> > > > to
> > > > say that stats reporting is not instantaneous?
> > > >
> > > >
> > > Unless that delay manifests in executing an UPDATE in a session then
> > > looking at these views in the same session and not seeing that update
> > > reflected I wouldn't mention it.
> >
> > Depending on which stats you're looking at, yes, that could totally
> happen. I
> > don't think the issue is not seeing changes from the current transaction
> > though - it's that *after* commit you might not see them for a while
> (the're
> > transmitted not more than once a second, and can be delayed up to 60s if
> > there's contention).
>
> So the docs don't need any changes, I assume.
>
>
I dislike using the word accurate here now, it will be accurate, but we
don't promise perfect timeliness. So it needs to change:

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 04a04e0e5f..360807c8f9 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -652,9 +652,8 @@ vacuum insert threshold = vacuum base insert threshold
+ vacuum insert scale fac
tuples to be frozen by earlier vacuums. The number of obsolete tuples
and
the number of inserted tuples are obtained from the cumulative
statistics system;
it is a semi-accurate count updated by each <command>UPDATE</command>,
- <command>DELETE</command> and <command>INSERT</command> operation.
(It is
- only semi-accurate because some information might be lost under heavy
- load.) If the <structfield>relfrozenxid</structfield> value of the
table
+ <command>DELETE</command> and <command>INSERT</command> operation.
+ If the <structfield>relfrozenxid</structfield> value of the table
is more than <varname>vacuum_freeze_table_age</varname> transactions
old,
an aggressive vacuum is performed to freeze old tuples and advance
<structfield>relfrozenxid</structfield>; otherwise, only pages that
have been modified

However, also replace the remaining instance of "a semi-accurate count"
with "an eventually-consistent count".

...it is an eventually-consistent count updated by each UPDATE, DELETE, and
INSERT operation.

David J.