From 3f47e145f1869f147a807e5a2cb80d21a13e10ae Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 5 Mar 2012 14:08:52 -0500
Subject: [PATCH] Improve documentation around logging_collector and use of
stderr.
In backup.sgml, point out that you need to be using the logging collector
if you want to log messages from a failing archive_command script. (This
is an oversimplification, in that it will work without the collector as
long as you're not sending postmaster stderr to /dev/null; but it seems
like a good idea to encourage use of the collector to avoid problems
with multiple processes concurrently scribbling on one file.)
In config.sgml, do some wordsmithing of logging_collector discussion.
Per bug #6518 from Janning Vygen
---
doc/src/sgml/backup.sgml | 13 ++++++++++---
doc/src/sgml/config.sgml | 33 ++++++++++++++++++++++++---------
2 files changed, 34 insertions(+), 12 deletions(-)
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 843dc3de9fc..4227b666f42 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1279,9 +1279,6 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
This allows all complexity to be managed within the script, which
can be written in a popular scripting language such as
<application>bash</> or <application>perl</>.
- Any messages written to <literal>stderr</> from the script will appear
- in the database server log, allowing complex configurations to be
- diagnosed easily if they fail.
</para>
<para>
@@ -1310,6 +1307,16 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
</listitem>
</itemizedlist>
</para>
+
+ <tip>
+ <para>
+ When using an <varname>archive_command</varname> script, it's desirable
+ to enable <xref linkend="guc-logging-collector">.
+ Any messages written to <systemitem>stderr</> from the script will then
+ appear in the database server log, allowing complex configurations to
+ be diagnosed easily if they fail.
+ </para>
+ </tip>
</sect3>
</sect2>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 6e1378a9d6d..3e178759a29 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -3123,7 +3123,7 @@ SELECT * FROM parent WHERE key = 2400;
value</> (<acronym>CSV</>) format, which is convenient for
loading logs into programs.
See <xref linkend="runtime-config-logging-csvlog"> for details.
- <varname>logging_collector</varname> must be enabled to generate
+ <xref linkend="guc-logging-collector"> must be enabled to generate
CSV-format log output.
</para>
@@ -3163,24 +3163,39 @@ local0.* /var/log/postgresql
</indexterm>
<listitem>
<para>
- This parameter captures plain and CSV-format log messages
- sent to <application>stderr</> and redirects them into log files.
+ This parameter enables the <firstterm>logging collector</>, which
+ is a background process that captures log messages
+ sent to <systemitem>stderr</> and redirects them into log files.
This approach is often more useful than
logging to <application>syslog</>, since some types of messages
- might not appear in <application>syslog</> output (a common example
- is dynamic-linker failure messages).
+ might not appear in <application>syslog</> output. (One common
+ example is dynamic-linker failure messages; another is error messages
+ produced by scripts such as <varname>archive_command</>.)
This parameter can only be set at server start.
</para>
+ <note>
+ <para>
+ It is possible to log to <systemitem>stderr</> without using the
+ logging collector; the log messages will just go to wherever the
+ server's <systemitem>stderr</> is directed. However, that method is
+ only suitable for low log volumes, since it provides no convenient
+ way to rotate log files. Also, on some platforms not using the
+ logging collector can result in lost or garbled log output, because
+ multiple processes writing concurrently to the same log file can
+ overwrite each other's output.
+ </para>
+ </note>
+
<note>
<para>
The logging collector is designed to never lose messages. This means
that in case of extremely high load, server processes could be
- blocked due to trying to send additional log messages when the
+ blocked while trying to send additional log messages when the
collector has fallen behind. In contrast, <application>syslog</>
- prefers to drop messages if it cannot write them, which means it's
- less reliable in those cases but it will not block the rest of the
- system.
+ prefers to drop messages if it cannot write them, which means it
+ may fail to log some messages in such cases but it will not block
+ the rest of the system.
</para>
</note>
--
GitLab