mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation around logging_collector and use of stderr.

Browse Source 
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  from Janning Vygen
This commit is contained in:
Tom Lane 2012-03-05 14:08:52 -05:00
parent cecdf6d459
commit 3f47e145f1
2 changed files with 34 additions and 12 deletions

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

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