Downloads
Home   >   mailing lists

Thread: Clarify VACUUM FULL exclusion in total_vacuum_time docs

Clarify VACUUM FULL exclusion in total_vacuum_time docs

From
Fujii Masao
Date:
Hi,

Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
we should add the same clarification to the description of total_vacuum_time.
This field also excludes VACUUM FULL, and without this note, users might
mistakenly think the time spent on VACUUM FULL is included. Thought?

         <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>

Regards,

-- 
Fujii Masao
NTT DATA Japan Corporation

Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs

From
"David G. Johnston"
Date:
On Friday, June 6, 2025, Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
Hi,

Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
we should add the same clarification to the description of total_vacuum_time.
This field also excludes VACUUM FULL, and without this note, users might
mistakenly think the time spent on VACUUM FULL is included. Thought?

        <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>

 Makes sense.  Our naming this table rewrite vacuum full does confuse people into thinking it is related to vacuum.

David J.
 

Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs

From
Robert Treat
Date:
On Fri, Jun 6, 2025 at 9:57 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
> On Friday, June 6, 2025, Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
>>
>> Hi,
>>
>> Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
>> that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
>> we should add the same clarification to the description of total_vacuum_time.
>> This field also excludes VACUUM FULL, and without this note, users might
>> mistakenly think the time spent on VACUUM FULL is included. Thought?
>>
>>         <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>
>
>
>  Makes sense.  Our naming this table rewrite vacuum full does confuse people into thinking it is related to vacuum.
>

+1 for this change, but I think we should also update
n_ins_since_vacuum as well, no?


Robert Treat
https://xzilla.net

Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs

From
Fujii Masao
Date:

On 2025/06/07 0:13, Robert Treat wrote:
> On Fri, Jun 6, 2025 at 9:57 AM David G. Johnston
> <david.g.johnston@gmail.com> wrote:
>> On Friday, June 6, 2025, Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
>>>
>>> Hi,
>>>
>>> Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
>>> that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
>>> we should add the same clarification to the description of total_vacuum_time.
>>> This field also excludes VACUUM FULL, and without this note, users might
>>> mistakenly think the time spent on VACUUM FULL is included. Thought?
>>>
>>>          <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>
>>
>>
>>   Makes sense.  Our naming this table rewrite vacuum full does confuse people into thinking it is related to vacuum.
>>
>
> +1 for this change,

Thanks both for the review!


> but I think we should also update
> n_ins_since_vacuum as well, no?

I didn't update n_ins_since_vacuum since it's mainly used by autovacuum rather
than end users, and there haven't been any complaints about the current
description so far. That said, I don't have a strong opinion either way,
so I'm fine with making the change if others think it's worthwhile.

Regards,

--
Fujii Masao
NTT DATA Japan Corporation

Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs

From
Robert Treat
Date:
On Thu, Jun 12, 2025 at 10:28 PM Fujii Masao
<masao.fujii@oss.nttdata.com> wrote:
> On 2025/06/07 0:13, Robert Treat wrote:
> > On Fri, Jun 6, 2025 at 9:57 AM David G. Johnston
> > <david.g.johnston@gmail.com> wrote:
> >> On Friday, June 6, 2025, Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
> >>>
> >>> Hi,
> >>>
> >>> Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
> >>> that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
> >>> we should add the same clarification to the description of total_vacuum_time.
> >>> This field also excludes VACUUM FULL, and without this note, users might
> >>> mistakenly think the time spent on VACUUM FULL is included. Thought?
> >>>
> >>>          <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>
> >>
> >>
> >>   Makes sense.  Our naming this table rewrite vacuum full does confuse people into thinking it is related to
vacuum.
> >>
> >
> > +1 for this change,
>
> Thanks both for the review!
>
>
> > but I think we should also update
> > n_ins_since_vacuum as well, no?
>
> I didn't update n_ins_since_vacuum since it's mainly used by autovacuum rather
> than end users, and there haven't been any complaints about the current
> description so far. That said, I don't have a strong opinion either way,
> so I'm fine with making the change if others think it's worthwhile.
>

Well, I admit I mostly mentioned it because when I noticed this one
wasn't documented the same way the other ones were, I second-guessed
myself about if I knew how it really behaved and did a quick test to
confirm :-)
I suspect others might have similar confusion.

Robert Treat
https://xzilla.net

Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs

From
Fujii Masao
Date:

On 2025/06/13 21:09, Robert Treat wrote:
> Well, I admit I mostly mentioned it because when I noticed this one
> wasn't documented the same way the other ones were, I second-guessed
> myself about if I knew how it really behaved and did a quick test to
> confirm :-)
> I suspect others might have similar confusion.

Maybe I failed to follow your point here... Are you suggesting it's worth
mentioning that n_ins_since_vacuum doesn't count VACUUM FULL, to help
avoid potential user confusion?  If so, since n_ins_since_vacuum was
introduced in v13, we'd need to backpatch that documentation change to v13?

As for total_vacuum_time, since it's new in v18, I'd like to apply
the proposed change there.

Regards,

-- 
Fujii Masao
NTT DATA Japan Corporation

Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs

From
Robert Treat
Date:
On Tue, Jun 17, 2025 at 10:54 AM Fujii Masao
<masao.fujii@oss.nttdata.com> wrote:
> On 2025/06/13 21:09, Robert Treat wrote:
> > Well, I admit I mostly mentioned it because when I noticed this one
> > wasn't documented the same way the other ones were, I second-guessed
> > myself about if I knew how it really behaved and did a quick test to
> > confirm :-)
> > I suspect others might have similar confusion.
>
> Maybe I failed to follow your point here... Are you suggesting it's worth
> mentioning that n_ins_since_vacuum doesn't count VACUUM FULL, to help
> avoid potential user confusion?  If so, since n_ins_since_vacuum was
> introduced in v13, we'd need to backpatch that documentation change to v13?
>
> As for total_vacuum_time, since it's new in v18, I'd like to apply
> the proposed change there.
>

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.

Robert Treat
https://xzilla.net