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

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 843dc3de9fcfb2fccef50706cca676e666929c06..4227b666f4274c8815c8e833d327f8009e60377f 100644 (file)
--- 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 6e1378a9d6dc8dc633fc56a1bc8450a1cd7c1861..3e178759a29e11b3346b7796b32f853aae9b4323 100644 (file)
--- 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.
-        <varname>logging_collector> must be enabled to generate
+        <xref linkend="guc-logging-collector"> 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.