Re: BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented

On 2019-Jul-17, Daniel Gustafsson wrote:

> > The `autovacuum_vacuum_cost_delay` setting:
> >
> > https://www.postgresql.org/docs/devel/runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-COST-DELAY
> >
> > …does not specify its units (seconds? milliseconds?) explicitly.
>
> The description of the setting contains "The default value is 2 milliseconds.”
> which to me implies that the unit is measured in milliseconds. If we want to
> spell it out, we could add the unit like how many other on the same page does:
>
> - Specifies the cost delay value that will be used in automatic
> + Specifies the cost delay value (in milliseconds) that will be used in automatic

But you can specify other units, so this would be wrong. Example:

$ postmaster -c autovacuum_vacuum_cost_delay=100us

55432 13devel 17056=# show autovacuum_vacuum_cost_delay ;
autovacuum_vacuum_cost_delay
──────────────────────────────
100us
(1 fila)

I guess you could suggest to say "in milliseconds unless some other unit
is specified" but that seems overly verbose and it would have to be
added to every single parameter's description. Section 19.1.1 already
contains this:

Numeric with Unit: Some numeric parameters have an implicit unit,
because they describe quantities of memory or time. The unit might
be bytes, kilobytes, blocks (typically eight kilobytes),
milliseconds, seconds, or minutes. An unadorned numeric value for
one of these settings will use the setting's default unit, which can
be learned from pg_settings.unit. For convenience, settings can be
given with a unit specified explicitly, for example '120 ms' for a
time value, and they will be converted to whatever the parameter's
actual unit is. Note that the value must be written as a string
(with quotes) to use this feature. The unit name is case-sensitive,
and there can be whitespace between the numeric value and the unit.

Valid memory units are B (bytes), kB (kilobytes), MB (megabytes), GB
(gigabytes), and TB (terabytes). The multiplier for memory units is
1024, not 1000.

Valid time units are us (microseconds), ms (milliseconds), s
(seconds), min (minutes), h (hours), and d (days).

If a fractional value is specified with a unit, it will be rounded
to a multiple of the next smaller unit if there is one. For example,
30.1 GB will be converted to 30822 MB not 32319628902 B. If the
parameter is of integer type, a final rounding to integer occurs
after any units conversion.

Now you could complain that this is inconsistent with other
descriptions; for example, log_autovacuum_min_duration talks about
milliseconds, which sounds a bit archaic to me:

Causes each action executed by autovacuum to be logged if it ran for
at least the specified number of milliseconds. Setting this to zero
logs all autovacuum actions. -1 (the default) disables logging
autovacuum actions. For example, if you set this to 250ms then all
automatic vacuums and analyzes that run 250ms or longer will be
logged. In addition, when this parameter is set to any value other
than -1, a message will be logged if an autovacuum action is skipped
due to a conflicting lock or a concurrently dropped relation.
Enabling this parameter can be helpful in tracking autovacuum
activity. This parameter can only be set in the postgresql.conf file
or on the server command line; but the setting can be overridden for
individual tables by changing table storage parameters.

I'm not really sure what's a good way to attack this problem, but I
doubt that focusing on just one description is a sufficient solution.

--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services