Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit e076ee6

Browse files
committed
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
1 parent ef03b34 commit e076ee6

File tree

2 files changed

+34
-12
lines changed

2 files changed

+34
-12
lines changed

doc/src/sgml/backup.sgml

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1277,9 +1277,6 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
12771277
This allows all complexity to be managed within the script, which
12781278
can be written in a popular scripting language such as
12791279
<application>bash</> or <application>perl</>.
1280-
Any messages written to <literal>stderr</> from the script will appear
1281-
in the database server log, allowing complex configurations to be
1282-
diagnosed easily if they fail.
12831280
</para>
12841281

12851282
<para>
@@ -1308,6 +1305,16 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
13081305
</listitem>
13091306
</itemizedlist>
13101307
</para>
1308+
1309+
<tip>
1310+
<para>
1311+
When using an <varname>archive_command</varname> script, it's desirable
1312+
to enable <xref linkend="guc-logging-collector">.
1313+
Any messages written to <systemitem>stderr</> from the script will then
1314+
appear in the database server log, allowing complex configurations to
1315+
be diagnosed easily if they fail.
1316+
</para>
1317+
</tip>
13111318
</sect3>
13121319
</sect2>
13131320

doc/src/sgml/config.sgml

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2961,7 +2961,7 @@ SELECT * FROM parent WHERE key = 2400;
29612961
value</> (<acronym>CSV</>) format, which is convenient for
29622962
loading logs into programs.
29632963
See <xref linkend="runtime-config-logging-csvlog"> for details.
2964-
<varname>logging_collector</varname> must be enabled to generate
2964+
<xref linkend="guc-logging-collector"> must be enabled to generate
29652965
CSV-format log output.
29662966
</para>
29672967

@@ -2993,24 +2993,39 @@ local0.* /var/log/postgresql
29932993
</indexterm>
29942994
<listitem>
29952995
<para>
2996-
This parameter captures plain and CSV-format log messages
2997-
sent to <application>stderr</> and redirects them into log files.
2996+
This parameter enables the <firstterm>logging collector</>, which
2997+
is a background process that captures log messages
2998+
sent to <systemitem>stderr</> and redirects them into log files.
29982999
This approach is often more useful than
29993000
logging to <application>syslog</>, since some types of messages
3000-
might not appear in <application>syslog</> output (a common example
3001-
is dynamic-linker failure messages).
3001+
might not appear in <application>syslog</> output. (One common
3002+
example is dynamic-linker failure messages; another is error messages
3003+
produced by scripts such as <varname>archive_command</>.)
30023004
This parameter can only be set at server start.
30033005
</para>
30043006

3007+
<note>
3008+
<para>
3009+
It is possible to log to <systemitem>stderr</> without using the
3010+
logging collector; the log messages will just go to wherever the
3011+
server's <systemitem>stderr</> is directed. However, that method is
3012+
only suitable for low log volumes, since it provides no convenient
3013+
way to rotate log files. Also, on some platforms not using the
3014+
logging collector can result in lost or garbled log output, because
3015+
multiple processes writing concurrently to the same log file can
3016+
overwrite each other's output.
3017+
</para>
3018+
</note>
3019+
30053020
<note>
30063021
<para>
30073022
The logging collector is designed to never lose messages. This means
30083023
that in case of extremely high load, server processes could be
3009-
blocked due to trying to send additional log messages when the
3024+
blocked while trying to send additional log messages when the
30103025
collector has fallen behind. In contrast, <application>syslog</>
3011-
prefers to drop messages if it cannot write them, which means it's
3012-
less reliable in those cases but it will not block the rest of the
3013-
system.
3026+
prefers to drop messages if it cannot write them, which means it
3027+
may fail to log some messages in such cases but it will not block
3028+
the rest of the system.
30143029
</para>
30153030
</note>
30163031

0 commit comments

Comments
 (0)