diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index 843dc3de9fcfb2fccef50706cca676e666929c06..4227b666f4274c8815c8e833d327f8009e60377f 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 6e1378a9d6dc8dc633fc56a1bc8450a1cd7c1861..3e178759a29e11b3346b7796b32f853aae9b4323 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>