From bb2ff5f2d4593854816c05992a5d24b3af88b000 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 20 Nov 2001 04:27:49 +0000
Subject: [PATCH] Expand discussion of logfile management a little bit.

---
 doc/src/sgml/maintenance.sgml | 63 ++++++++++++++++++++++++++++++++---
 doc/src/sgml/runtime.sgml     |  8 +++--
 2 files changed, 63 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index f58af65ca7..2f3e080212 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.7 2001/11/18 22:17:30 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.8 2001/11/20 04:27:49 tgl Exp $
 -->
 
 <chapter id="maintenance">
@@ -34,10 +34,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.7 2001/11/18 22:17:30
   </para>
 
   <para>
-  It is also necessary to rotate the database server log file that is specified 
-  when the <application>postmaster</application> is started.  If you are using
-  <application>syslog</application>, you can send a <literal>SIGHUP</literal>
-  signal to the syslog daemon to force it to start writing a new log file.
+   Something else that might need periodic attention is log file management.
+   This is discussed in <xref linkend="logfile-maintenance">.
   </para>
 
   <para>
@@ -367,6 +365,61 @@ VACUUM
 
   </sect2>
  </sect1>
+
+ <sect1 id="logfile-maintenance">
+  <title>Log File Maintenance</title>
+
+  <indexterm zone="logfile-maintenance">
+   <primary>log files</primary>
+  </indexterm>
+
+  <para>
+   It's a good idea to save the database server's log output somewhere,
+   rather than just routing it to <filename>/dev/null</>.  The log output
+   is invaluable when it comes time to diagnose problems.  However, the
+   log output tends to be voluminuous (especially at higher debug levels)
+   and you won't want to save it indefinitely.  You need to <quote>rotate</>
+   the log files so that new log files are started and old ones thrown
+   away every so often.
+  </para>
+
+  <para>
+   If you simply direct the postmaster's stderr into a file, the only way
+   to truncate the log file is to stop and restart the postmaster.  This
+   may be okay for development setups but you won't want to run a production
+   server that way.
+  </para>
+
+  <para>
+   The simplest production-grade approach to managing log output is to send it
+   all to <application>syslog</> and let <application>syslog</> deal with file
+   rotation.  To do this, make sure <productname>Postgres</> was built with
+   the <option>--enable-syslog</> configure option, and set
+   <literal>syslog</> to 2
+   (log to syslog only) in <filename>postgresql.conf</>.
+   Then you can send a <literal>SIGHUP</literal> signal to the
+   <application>syslog</> daemon whenever you want to force it to start
+   writing a new log file.
+  </para>
+
+  <para>
+   On many systems, however, syslog is not very reliable, particularly
+   with large log messages; it may truncate or drop messages just when
+   you need them the most.  You may find it more useful to pipe the
+   <application>postmaster</>'s stderr to some type of log rotation script.
+   If you start the postmaster with <application>pg_ctl</>, then the
+   postmaster's stderr is already redirected to stdout, so you just need a
+   pipe command:
+   
+<screen>
+<userinput>pg_ctl start | logrotate</userinput>
+</screen>
+
+   The <productname>Postgres</> distribution doesn't include a suitable
+   log rotation program, but there are many available on the net;
+   one is included in the Apache distribution, for example.
+  </para>
+ </sect1>
 </chapter>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 51be109ab2..81141607df 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.95 2001/11/19 03:58:24 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.96 2001/11/20 04:27:49 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -171,9 +171,11 @@ NOTICE:  Initializing database with en_US collation order.
 <screen>
 &gt; <userinput>postmaster -D /usr/local/pgsql/data &gt; logfile 2&gt;&amp;1 &amp;</userinput>
 </screen>
-   It is an extremely good idea to keep the server output around
-   somewhere, as indicated here. It will help both for auditing
+   It is an extremely good idea to keep the server's stdout and stderr
+   output around somewhere, as suggested here. It will help both for auditing
    purposes and to diagnose problems.
+   (See <xref linkend="logfile-maintenance"> for a more thorough discussion
+   of logfile handling.)
   </para>
 
   <para>