agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Fujii Masao <masao.fujii@oss.nttdata.com>
To: Robert Treat <rob@xzilla.net>
Cc: David G. Johnston <david.g.johnston@gmail.com>
Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Subject: Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
Date: Tue, 15 Jul 2025 01:51:30 +0900
Message-ID: <b1cfd248-6860-4a95-bb62-07009f5e486e@oss.nttdata.com> (raw)
In-Reply-To: <CAJSLCQ27T5utjOipbaqArGCPS1VT+2Uqx_g2NH3od_spHxkoig@mail.gmail.com>
References: <2ac375d1-591b-4f1b-a2af-f24335567866@oss.nttdata.com>
<CAKFQuwYgErraNuAUme-6dSwmwNSSStC8SL7560Qy2sAtUG5J+Q@mail.gmail.com>
<CABV9wwMs4g9nq-fKy=fFqU-rQUf6fiCqJg4_+MkqOnJE1n2TBA@mail.gmail.com>
<f58eb77f-0d8f-4f58-bed2-a100bd7e0814@oss.nttdata.com>
<CAJSLCQ3YPKaB7tQDyg8BbVuo80EGn_j6kycNGG3oZB59P8tgrg@mail.gmail.com>
<bb97b8d4-2f44-4b95-9b82-a54ecbce9e76@oss.nttdata.com>
<CAJSLCQ27T5utjOipbaqArGCPS1VT+2Uqx_g2NH3od_spHxkoig@mail.gmail.com>
On 2025/06/18 6:53, Robert Treat wrote:
> I think the more cases where you document this behavior (and I do like
> the idea of documenting it for total_vacuum_time), the more one is
> likely to think that places where it is not documented operate
> differently. To that end, I think documenting it for
> n_ins_since_vacuum as well is a good idea, but I don't feel strongly
> that it needs to be backpatched; the old documentation wasn't wrong
> per se, rather this is a documentation improvement as a result of new
> development.
Agreed. The attached patch updates the docs to clarify that both
total_vacuum_time and n_ins_since_vacuum exclude VACUUM FULL.
Unless there are any objections, I'll commit this to master and
back-patch it to v18 only.
Regards,
--
Fujii Masao
NTT DATA Japan Corporation
From b1e64ee62915b883369a46e6add417acde15da88 Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Tue, 15 Jul 2025 01:21:24 +0900
Subject: [PATCH v1] doc: Clarify that total_vacuum_time excludes VACUUM FULL.
The last_vacuum and vacuum_count fields in pg_stat_all_tables already
state that they do not include VACUUM FULL. However, total_vacuum_time,
which also excludes VACUUM FULL, did not mention this. This could
mislead users into thinking VACUUM FULL time is included.
To address this, this commit updates the documentation for
pg_stat_all_tables to explicitly state that total_vacuum_time does not
count VACUUM FULL.
Back-patched to v18, where total_vacuum_time was introduced.
Additionally, this commit clarifies that n_ins_since_vacuum also
excludes VACUUM FULL. Although n_ins_since_vacuum was added in v13,
we are not back-patching this change to stable branches, as it is
a documentation improvement, not a bug fix.
Author: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Discussion: https://postgr.es/m/2ac375d1-591b-4f1b-a2af-f24335567866@oss.nttdata.com
Backpatch-through: 18
---
doc/src/sgml/monitoring.sgml | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 4265a22d4de..823afe1b30b 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -3980,6 +3980,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
</para>
<para>
Estimated number of rows inserted since this table was last vacuumed
+ (not counting <command>VACUUM FULL</command>)
</para></entry>
</row>
@@ -4066,7 +4067,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
<structfield>total_vacuum_time</structfield> <type>double precision</type>
</para>
<para>
- Total time this table has been manually vacuumed, in milliseconds.
+ Total time this table has been manually vacuumed, in milliseconds
+ (not counting <command>VACUUM FULL</command>).
(This includes the time spent sleeping due to cost-based delays.)
</para></entry>
</row>
--
2.49.0
Attachments:
[text/plain] v1-0001-doc-Clarify-that-total_vacuum_time-excludes-VACUU.patch (2.3K, ../b1cfd248-6860-4a95-bb62-07009f5e486e@oss.nttdata.com/2-v1-0001-doc-Clarify-that-total_vacuum_time-excludes-VACUU.patch)
download | inline diff:
From b1e64ee62915b883369a46e6add417acde15da88 Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Tue, 15 Jul 2025 01:21:24 +0900
Subject: [PATCH v1] doc: Clarify that total_vacuum_time excludes VACUUM FULL.
The last_vacuum and vacuum_count fields in pg_stat_all_tables already
state that they do not include VACUUM FULL. However, total_vacuum_time,
which also excludes VACUUM FULL, did not mention this. This could
mislead users into thinking VACUUM FULL time is included.
To address this, this commit updates the documentation for
pg_stat_all_tables to explicitly state that total_vacuum_time does not
count VACUUM FULL.
Back-patched to v18, where total_vacuum_time was introduced.
Additionally, this commit clarifies that n_ins_since_vacuum also
excludes VACUUM FULL. Although n_ins_since_vacuum was added in v13,
we are not back-patching this change to stable branches, as it is
a documentation improvement, not a bug fix.
Author: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Discussion: https://postgr.es/m/2ac375d1-591b-4f1b-a2af-f24335567866@oss.nttdata.com
Backpatch-through: 18
---
doc/src/sgml/monitoring.sgml | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 4265a22d4de..823afe1b30b 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -3980,6 +3980,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
</para>
<para>
Estimated number of rows inserted since this table was last vacuumed
+ (not counting <command>VACUUM FULL</command>)
</para></entry>
</row>
@@ -4066,7 +4067,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
<structfield>total_vacuum_time</structfield> <type>double precision</type>
</para>
<para>
- Total time this table has been manually vacuumed, in milliseconds.
+ Total time this table has been manually vacuumed, in milliseconds
+ (not counting <command>VACUUM FULL</command>).
(This includes the time spent sleeping due to cost-based delays.)
</para></entry>
</row>
--
2.49.0
view thread (12+ messages) latest in thread
Message-ID: <b1cfd248-6860-4a95-bb62-07009f5e486e@oss.nttdata.com>
Permalink: ../b1cfd248-6860-4a95-bb62-07009f5e486e@oss.nttdata.com/
Also on: postgresql.org/message-id/b1cfd248-6860-4a95-bb62-07009f5e486e@oss.nttdata.com
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: masao.fujii@oss.nttdata.com, rob@xzilla.net, david.g.johnston@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
In-Reply-To: <b1cfd248-6860-4a95-bb62-07009f5e486e@oss.nttdata.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox