Tweak docs for log_statement_sample_rate

Author: Justin Pryzby, partly after a suggestion from Masahiko Sawada
Discussion: https://postgr.es/m/[email protected]
Discussion: https://postgr.es/m/CAD21AoB9+y8N4+Fan-ne-_7J5yTybPttxeVKfwUocKp4zT1vNQ@mail.gmail.com

3 files changed, 20 insertions, 18 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 915296310c..4cbcc7a8e5 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -5821,11 +5821,12 @@ local0.*    /var/log/postgresql
          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>.
-         Setting this to zero prints all statement durations. Minus-one (the default)
-         disables logging statement durations. For example, if you set it to
-         <literal>250ms</literal> then all SQL statements that run 250ms or longer
-         will be logged. Enabling this parameter can be helpful in tracking down
-         unoptimized queries in your applications.
+         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
+         <literal>250ms</literal>, then all SQL statements that run 250ms or
+         longer will be logged. Enabling this parameter can be helpful in
+         tracking down unoptimized queries in your applications.
          Only superusers can change this setting.
         </para>
 
@@ -5859,14 +5860,15 @@ local0.*    /var/log/postgresql
       </term>
        <listitem>
         <para>
-         Determines the fraction of the statements that exceed
-         <xref linkend="guc-log-min-duration-statement"/> which to log.
-         The default is <literal>1</literal>, meaning log to all such
+         Determines the fraction of statements that exceed
+         <xref linkend="guc-log-min-duration-statement"/> to be logged.
+         The default is <literal>1</literal>, meaning log all such
          statements.
-         Setting this to zero disables logging, same as setting
-         <varname>log_min_duration_statement</varname>
-         to minus-one. <varname>log_statement_sample_rate</varname>
-         is helpful when the traffic is too high to log all queries.
+         Setting this to zero disables logging by duration, same as setting
+         <varname>log_min_duration_statement</varname> to
+         <literal>-1</literal>.
+         <varname>log_statement_sample_rate</varname> is helpful when the
+         traffic is too high to log all queries.
         </para>
        </listitem>
       </varlistentry>
@@ -6144,7 +6146,7 @@ local0.*    /var/log/postgresql
 
        <note>
         <para>
-         The difference between setting this option and setting
+         The difference between enabling <varname>log_duration</varname> and setting
          <xref linkend="guc-log-min-duration-statement"/> to zero is that
          exceeding <varname>log_min_duration_statement</varname> forces the text of
          the query to be logged, but this option doesn't.  Thus, if
diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c
index 83a9fc2b4c..0806a340f8 100644
--- a/src/backend/utils/misc/guc.c
+++ b/src/backend/utils/misc/guc.c
@@ -3378,8 +3378,8 @@ static struct config_real ConfigureNamesReal[] =
 
 	{
 		{"log_statement_sample_rate", PGC_SUSET, LOGGING_WHEN,
-			gettext_noop("Fraction of statements over log_min_duration_statement to log."),
-			gettext_noop("If you only want a sample, use a value between 0 (never "
+			gettext_noop("Fraction of statements exceeding log_min_duration_statement to be logged."),
+			gettext_noop("If you only want a sample, use a value between 0.0 (never "
 						 "log) and 1.0 (always log).")
 		},
 		&log_statement_sample_rate,
diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample
index f31d419f79..bbbeb4bb15 100644
--- a/src/backend/utils/misc/postgresql.conf.sample
+++ b/src/backend/utils/misc/postgresql.conf.sample
@@ -491,9 +491,9 @@
 					# 0 logs all statement, > 0 logs only statements running at
 					# least this number of milliseconds.
 
-#log_statement_sample_rate = 1	# Fraction of logged statements over
-					# log_min_duration_statement. 1.0 logs all statements,
-					# 0 never logs.
+#log_statement_sample_rate = 1.0	# Fraction of logged statements exceeding
+					# log_min_duration_statement to be logged.
+					# 1.0 logs all such statements, 0.0 never logs.
 
 #log_transaction_sample_rate = 0.0	# Fraction of transactions whose statements
 					# are logged regardless of their duration. 1.0 logs all