public inbox for [email protected]help / color / mirror / Atom feed
BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented 7+ messages / 5 participants [nested] [flat]
* BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented @ 2019-07-16 16:26 PG Bug reporting form <[email protected]> 0 siblings, 1 reply; 7+ messages in thread From: PG Bug reporting form @ 2019-07-16 16:26 UTC (permalink / raw) To: [email protected]; +Cc: [email protected] The following bug has been logged on the website: Bug reference: 15912 Logged by: Basil Bourque Email address: [email protected] PostgreSQL version: 12beta2 Operating system: macOS Description: The `autovacuum_vacuum_cost_delay` setting: https://www.postgresql.org/docs/devel/runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-COST-DELA... …does not specify its units (seconds? milliseconds?) explicitly. Previously, one could guess that the units were milliseconds. But now in Postgres 12 the argument type changed from `integer` to `floating point`. So now the units are quite unclear. I am guessing a whole number means milliseconds, while the fractional part represents microseconds. But that is only a guess. Should be documented. ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented @ 2019-07-17 16:03 Daniel Gustafsson <[email protected]> parent: PG Bug reporting form <[email protected]> 0 siblings, 1 reply; 7+ messages in thread From: Daniel Gustafsson @ 2019-07-17 16:03 UTC (permalink / raw) To: [email protected]; PostgreSQL mailing lists <[email protected]> > On 16 Jul 2019, at 18:26, PG Bug reporting form <[email protected]> wrote: > > The following bug has been logged on the website: > > Bug reference: 15912 > Logged by: Basil Bourque > Email address: [email protected] > PostgreSQL version: 12beta2 > Operating system: macOS > Description: > > The `autovacuum_vacuum_cost_delay` setting: > > https://www.postgresql.org/docs/devel/runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-COST-DELA... > > …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 cheers ./daniel ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented @ 2019-07-26 22:02 Alvaro Herrera <[email protected]> parent: Daniel Gustafsson <[email protected]> 0 siblings, 1 reply; 7+ messages in thread From: Alvaro Herrera @ 2019-07-26 22:02 UTC (permalink / raw) To: Daniel Gustafsson <[email protected]>; +Cc: [email protected]; PostgreSQL mailing lists <[email protected]> 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-DELA... > > > > …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 ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented @ 2019-07-27 21:41 Bruce Momjian <[email protected]> parent: Alvaro Herrera <[email protected]> 0 siblings, 1 reply; 7+ messages in thread From: Bruce Momjian @ 2019-07-27 21:41 UTC (permalink / raw) To: Alvaro Herrera <[email protected]>; +Cc: Daniel Gustafsson <[email protected]>; [email protected]; PostgreSQL mailing lists <[email protected]> On Fri, Jul 26, 2019 at 06:02:42PM -0400, Alvaro Herrera wrote: > 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. Yes, I looked at this earlier in the week and had the same conclusion. I went over config.sgml and saw many inconsistencies of the same type being complained about here. I went through the file and found a number of cases using milliseconds and kilobytes that were unclear, and adjusted them. I dealt only with the cases where the base unit (seconds/bytes) was not the default unit. Patch attached. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription + Attachments: [text/x-diff] default.diff (10.0K, 2-default.diff) download | inline diff: diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index c91e3e1550..15d0a75d4c 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -947,7 +947,7 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies the number of milliseconds that transmitted data may + Specifies duration (defaults to milliseconds) that transmitted data may remain unacknowledged before a connection is forcibly closed. A value of 0 uses the system default. This parameter is supported only on systems that support @@ -1805,7 +1805,7 @@ include_dir 'conf.d' for temporary files, such as sort and hash temporary files, or the storage file for a held cursor. A transaction attempting to exceed this limit will be canceled. - The value is specified in kilobytes, and <literal>-1</literal> (the + The default unit is kilobytes, and <literal>-1</literal> (the default) means no limit. Only superusers can change this setting. </para> @@ -1893,7 +1893,7 @@ include_dir 'conf.d' </term> <listitem> <para> - The length of time, in milliseconds, that the process will sleep + The duration (defaults to milliseconds) that the process will sleep when the cost limit has been exceeded. The default value is zero, which disables the cost-based vacuum delay feature. Positive values enable cost-based vacuuming. @@ -2018,11 +2018,11 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies the delay between activity rounds for the + Specifies the delay (defaults to milliseconds) between activity rounds for the background writer. In each round the writer issues writes for some number of dirty buffers (controllable by the following parameters). It then sleeps for <varname>bgwriter_delay</varname> - milliseconds, and repeats. When there are no dirty buffers in the + duration, and repeats. When there are no dirty buffers in the buffer pool, though, it goes into a longer sleep regardless of <varname>bgwriter_delay</varname>. The default value is 200 milliseconds (<literal>200ms</literal>). Note that on many systems, the @@ -2781,9 +2781,10 @@ include_dir 'conf.d' <listitem> <para> Specifies how often the WAL writer flushes WAL. After flushing WAL it - sleeps for <varname>wal_writer_delay</varname> milliseconds, unless woken up + sleeps for <varname>wal_writer_delay</varname> duration (defaults + to milliseconds), unless woken up by an asynchronously committing transaction. If the last flush - happened less than <varname>wal_writer_delay</varname> milliseconds ago and + happened less than <varname>wal_writer_delay</varname> duration ago and less than <varname>wal_writer_flush_after</varname> bytes of WAL have been produced since, then WAL is only written to the operating system, not flushed to disk. @@ -2806,7 +2807,8 @@ include_dir 'conf.d' <listitem> <para> Specifies how often the WAL writer flushes WAL. If the last flush - happened less than <varname>wal_writer_delay</varname> milliseconds ago and + happened less than <varname>wal_writer_delay</varname> duration ago + (defaults to milliseconds) and less than <varname>wal_writer_flush_after</varname> bytes of WAL have been produced since, then WAL is only written to the operating system, not flushed to disk. If <varname>wal_writer_flush_after</varname> is set @@ -3659,7 +3661,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows <listitem> <para> Terminate replication connections that are inactive longer - than the specified number of milliseconds. This is useful for + than the specified duration (defaults to milliseconds). This is useful for the sending server to detect a standby crash or network outage. A value of zero disables the timeout mechanism. The default value is 60 seconds. With a cluster distributed across multiple geographic @@ -4111,7 +4113,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" <listitem> <para> Terminate replication connections that are inactive longer - than the specified number of milliseconds. This is useful for + than the specified duration (defaults to milliseconds). This is useful for the receiving standby server to detect a primary node crash or network outage. A value of zero disables the timeout mechanism. This parameter @@ -5606,7 +5608,7 @@ local0.* /var/log/postgresql <para> When <varname>logging_collector</varname> is enabled, this parameter determines the maximum size of an individual log file. - After this many kilobytes have been emitted into a log file, + After this many bytes (default units is kilobytes) have been emitted into a log file, a new log file will be created. Set to zero to disable size-based creation of new log files. This parameter can only be set in the <filename>postgresql.conf</filename> @@ -5849,8 +5851,8 @@ local0.* /var/log/postgresql <listitem> <para> Causes the duration of each completed statement to be logged - if the statement ran for at least the specified number of - milliseconds, modulated by <varname>log_statement_sample_rate</varname>. + if the statement ran for at least the specified duration (defaults + to milliseconds), modulated by <varname>log_statement_sample_rate</varname>. Setting this to zero prints all statement durations. <literal>-1</literal> (the default) disables logging statements due to exceeding duration threshold; for example, if you set it to @@ -6498,7 +6500,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' A log entry is made for each temporary file when it is deleted. A value of zero logs all temporary file information, while positive values log only files whose size is greater than or equal to - the specified number of kilobytes. The + the specified number of bytes (default units is kilobytes). The default setting is -1, which disables such logging. Only superusers can change this setting. </para> @@ -6946,7 +6948,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <listitem> <para> 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 + least the specified duration (defaults to milliseconds). Setting this to zero logs all autovacuum actions. <literal>-1</literal> (the default) disables logging autovacuum actions. For example, if you set this to <literal>250ms</literal> then all automatic vacuums and analyzes that run @@ -7595,8 +7597,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; </term> <listitem> <para> - Abort any statement that takes more than the specified number of - milliseconds, starting from the time the command arrives at the server + Abort any statement that takes more than the specified duration + (defaults to milliseconds), starting from the time the command arrives at the server from the client. If <varname>log_min_error_statement</varname> is set to <literal>ERROR</literal> or lower, the statement that timed out will also be logged. A value of zero (the default) turns this off. @@ -7618,8 +7620,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; </term> <listitem> <para> - Abort any statement that waits longer than the specified number of - milliseconds while attempting to acquire a lock on a table, index, + Abort any statement that waits longer than the specified duration + (defaults to milliseconds) while attempting to acquire a lock on a table, index, row, or other database object. The time limit applies separately to each lock acquisition attempt. The limit applies both to explicit locking requests (such as <command>LOCK TABLE</command>, or <command>SELECT @@ -7654,7 +7656,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <listitem> <para> Terminate any session with an open transaction that has been idle for - longer than the specified duration in milliseconds. This allows any + longer than the specified duration (defaults to milliseconds). This allows any locks held by that session to be released and the connection slot to be reused; it also allows tuples visible only to this transaction to be vacuumed. See <xref linkend="routine-vacuuming"/> for more details about this. @@ -8490,7 +8492,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' </term> <listitem> <para> - This is the amount of time, in milliseconds, to wait on a lock + This is the duration (defaults to milliseconds), to wait on a lock before checking to see if there is a deadlock condition. The check for deadlock is relatively expensive, so the server doesn't run it every time it waits for a lock. We optimistically assume @@ -8509,7 +8511,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' <para> When <xref linkend="guc-log-lock-waits"/> is set, - this parameter also determines the length of time to wait before + this parameter also determines the duration to wait before a log message is issued about the lock wait. If you are trying to investigate locking delays you might want to set a shorter than normal <varname>deadlock_timeout</varname>. ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented @ 2019-10-09 01:49 Bruce Momjian <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 7+ messages in thread From: Bruce Momjian @ 2019-10-09 01:49 UTC (permalink / raw) To: Alvaro Herrera <[email protected]>; +Cc: Daniel Gustafsson <[email protected]>; [email protected]; PostgreSQL mailing lists <[email protected]> On Sat, Jul 27, 2019 at 05:41:30PM -0400, Bruce Momjian wrote: > On Fri, Jul 26, 2019 at 06:02:42PM -0400, Alvaro Herrera wrote: > > 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. > > Yes, I looked at this earlier in the week and had the same conclusion. > I went over config.sgml and saw many inconsistencies of the same type > being complained about here. > > I went through the file and found a number of cases using milliseconds > and kilobytes that were unclear, and adjusted them. I dealt only with > the cases where the base unit (seconds/bytes) was not the default unit. > Patch attached. I applied a modified version of this patch. I didn't backpatch it past PG 12 because earlier releases were just too different. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription + ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented @ 2019-10-24 18:37 Tom Lane <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 7+ messages in thread From: Tom Lane @ 2019-10-24 18:37 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Daniel Gustafsson <[email protected]>; [email protected]; [email protected]; [email protected] [ cc'ing pgsql-docs as well ] Bruce Momjian <[email protected]> writes: > I applied a modified version of this patch. I didn't backpatch it past > PG 12 because earlier releases were just too different. I happened to stumble across the effects of this patch while trying to improve our explanation of statement_timeout. I follow the goal of explaining what the default units are, but I really dislike the way you did it: + Abort any statement that takes more than the specified duration + (defaults to milliseconds), starting from the time the command arrives at the server from the client. ... I think this is confusingly bad English, and it's poor exposition because a minor detail (it must be pretty minor, if we got away without mentioning it at all for years) is injected into the middle of the basic statement of the variable's purpose. I think what we'd be better off doing is to write a separate sentence mentioning the units, in more or less the same way that we generally handle the default value. In <[email protected]> I suggested this revision for statement_timeout: Abort any statement that takes more than the specified duration. If <varname>log_min_error_statement</varname> is set to <literal>ERROR</literal> or lower, the statement that timed out will also be logged. If the value is specified as a plain number, it is measured in milliseconds by default. A value of zero (the default) disables the timeout. (I'm not quite sure whether the ending "by default" is worth writing or not.) Barring objections, I'll run around and make them all look like that. regards, tom lane ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented @ 2019-11-05 20:11 Bruce Momjian <[email protected]> parent: Tom Lane <[email protected]> 0 siblings, 0 replies; 7+ messages in thread From: Bruce Momjian @ 2019-11-05 20:11 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Daniel Gustafsson <[email protected]>; [email protected]; [email protected]; [email protected] On Thu, Oct 24, 2019 at 02:37:03PM -0400, Tom Lane wrote: > I think this is confusingly bad English, and it's poor exposition > because a minor detail (it must be pretty minor, if we got away > without mentioning it at all for years) is injected into the middle > of the basic statement of the variable's purpose. I think what we'd > be better off doing is to write a separate sentence mentioning the > units, in more or less the same way that we generally handle the > default value. In <[email protected]> I suggested > this revision for statement_timeout: > > Abort any statement that takes more than the specified duration. > If <varname>log_min_error_statement</varname> is set > to <literal>ERROR</literal> or lower, the statement that timed out > will also be logged. > If the value is specified as a plain number, it is measured in > milliseconds by default. > A value of zero (the default) disables the timeout. > > (I'm not quite sure whether the ending "by default" is worth writing > or not.) > > Barring objections, I'll run around and make them all look like that. Thanks for applying the improvement in your patch cfb7559083. I was torn between it being a minor issue and not wanting to devote a new sentence about it, which is why I awkwardly used parentheses. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription + ^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2019-11-05 20:11 UTC | newest] Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2019-07-16 16:26 BUG #15912: The units of `autovacuum_vacuum_cost_delay` setting should be documented PG Bug reporting form <[email protected]> 2019-07-17 16:03 ` Daniel Gustafsson <[email protected]> 2019-07-26 22:02 ` Alvaro Herrera <[email protected]> 2019-07-27 21:41 ` Bruce Momjian <[email protected]> 2019-10-09 01:49 ` Bruce Momjian <[email protected]> 2019-10-24 18:37 ` Tom Lane <[email protected]> 2019-11-05 20:11 ` Bruce Momjian <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox