From 3f47e145f1869f147a807e5a2cb80d21a13e10ae Mon Sep 17 00:00:00 2001 From: Tom Lane 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 843dc3de9f..4227b666f4 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 bash or perl. - Any messages written to stderr from the script will appear - in the database server log, allowing complex configurations to be - diagnosed easily if they fail. @@ -1310,6 +1307,16 @@ archive_command = 'local_backup_script.sh "%p" "%f"' + + + + When using an archive_command script, it's desirable + to enable . + Any messages written to stderr from the script will then + appear in the database server log, allowing complex configurations to + be diagnosed easily if they fail. + + diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 6e1378a9d6..3e178759a2 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -3123,7 +3123,7 @@ SELECT * FROM parent WHERE key = 2400; value (CSV) format, which is convenient for loading logs into programs. See for details. - logging_collector must be enabled to generate + must be enabled to generate CSV-format log output. @@ -3163,24 +3163,39 @@ local0.* /var/log/postgresql - This parameter captures plain and CSV-format log messages - sent to stderr and redirects them into log files. + This parameter enables the logging collector, which + is a background process that captures log messages + sent to stderr and redirects them into log files. This approach is often more useful than logging to syslog, since some types of messages - might not appear in syslog output (a common example - is dynamic-linker failure messages). + might not appear in syslog output. (One common + example is dynamic-linker failure messages; another is error messages + produced by scripts such as archive_command.) This parameter can only be set at server start. + + + It is possible to log to stderr without using the + logging collector; the log messages will just go to wherever the + server's 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. + + + 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, 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.