Create a built-in log rotation program, so that we no longer have to

recommend that people go get Apache's rotatelogs program.  Additional
benefits are that configuration is done through GUC, rather than
externally, and that the postmaster can monitor the log rotator and
restart it after failure (though we certainly hope that won't happen
often).
Andreas Pflug, some rework by Tom Lane.

2 files changed, 124 insertions, 30 deletions

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 91ead3dc168..7d1dafad318 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.36 2004/07/24 19:51:22 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.37 2004/08/05 23:32:10 tgl Exp $
 -->
 
 <chapter id="maintenance">
@@ -445,22 +445,52 @@ VACUUM
   </para>
 
   <para>
-   If you simply direct the <systemitem>stderr</> of the <command>postmaster</command> into a
-   file, the only way to truncate the log file is to stop and restart
+   If you simply direct the <systemitem>stderr</> of the
+   <command>postmaster</command> into a
+   file, you will have log output, but
+   the only way to truncate the log file is to stop and restart
    the <command>postmaster</command>. This may be OK if you are using
    <productname>PostgreSQL</productname> in a development environment,
    but few production servers would find this behavior acceptable.
   </para>
 
   <para>
-   The simplest production-grade approach to managing log output is to
+   A better approach is to send the <command>postmaster</>'s
+   <systemitem>stderr</> output to some type of log rotation program.
+   There is a built-in log rotation program, which you can use by
+   setting the configuration parameter <literal>redirect_stderr</> to
+   <literal>true</> in <filename>postgresql.conf</>.  The control
+   parameters for this program are described in <xref
+   linkend="runtime-config-logging-where">.
+  </para>
+
+  <para>
+   Alternatively, you might prefer to use an external log rotation
+   program, if you have one that you are already using with other
+   server software. For example, the <application>rotatelogs</application>
+   tool included in the <productname>Apache</productname> distribution
+   can be used with <productname>PostgreSQL</productname>.  To do this,
+   just pipe the <command>postmaster</>'s
+   <systemitem>stderr</> output to the desired program.
+   If you start the server with
+   <command>pg_ctl</>, then <systemitem>stderr</>
+   is already redirected to <systemitem>stdout</>, so you just need a
+   pipe command:
+
+<programlisting>
+pg_ctl start | rotatelogs /var/log/pgsql_log 86400
+</programlisting>
+  </para>
+
+  <para>
+   Another 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, set the
-   configuration parameter <literal>log_destination</> to 'syslog' (to log to
-   <application>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.  If you want to automate log
+   configuration parameter <literal>log_destination</> to <literal>syslog</>
+   (to log to <application>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.  If you want to automate log
    rotation, the <application>logrotate</application> program can be
    configured to work with log files from
    <application>syslog</application>.
@@ -471,27 +501,15 @@ VACUUM
    particularly with large log messages; it may truncate or drop messages
    just when you need them the most.  Also, on <productname>linux</>,
    <application>syslog</> will sync each message to disk, yielding poor
-   performance.  Use a <literal>-</> at the start of the file name
-   in the <application>syslog</> config file to disable this behavior.
+   performance.  (You can use a <literal>-</> at the start of the file name
+   in the <application>syslog</> config file to disable this behavior.)
   </para>
 
   <para>
-   You may find it more useful to pipe the
-   <systemitem>stderr</> of the <command>postmaster</> to some type of
-   log rotation program. If you start the server with
-   <command>pg_ctl</>, then the <systemitem>stderr</> of the <command>postmaster</command>
-   is already redirected to <systemitem>stdout</>, so you just need a
-   pipe command:
-
-<programlisting>
-pg_ctl start | rotatelogs /var/log/pgsql_log 86400
-</programlisting>
-
-   The <productname>PostgreSQL</> distribution doesn't include a
-   suitable log rotation program, but there are many available on the
-   Internet. For example, the <application>rotatelogs</application>
-   tool included in the <productname>Apache</productname> distribution
-   can be used with <productname>PostgreSQL</productname>.
+   Note that all the solutions described above take care of starting new
+   log files at configurable intervals, but they do not handle deletion
+   of old, no-longer-interesting log files.  You will also want to set
+   up a batch job to periodically delete old log files.
   </para>
  </sect1>
 </chapter>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 95a8c23c822..9f569712b08 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.271 2004/08/03 23:42:59 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.272 2004/08/05 23:32:10 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -1800,15 +1800,91 @@ SET ENABLE_SEQSCAN TO OFF;
 	 option to a list of desired log destinations separated by
 	 commas. The default is to log to <systemitem>stderr</systemitem> 
 	 only.
+         This option can only be set at server start or in the
+         <filename>postgresql.conf</filename> configuration file.
        </para>
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-redirect-stderr" xreflabel="redirect_stderr">
+      <term><varname>redirect_stderr</varname> (<type>boolean</type>)</term>
+       <listitem>
+        <para>
+	  This option allows messages sent to <application>stderr</> to be
+	  captured and redirected into log files.
+	  This option, in combination with logging to <application>stderr</>,
+	  is often more useful than
+	  logging to <application>syslog</>, since some types of messages
+	  may not appear in <application>syslog</> output (a common example
+	  is dynamic-linker failure messages).
+	  This option can only be set at server start.
+        </para>
+       </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-log-directory" xreflabel="log_directory">
+      <term><varname>log_directory</varname> (<type>string</type>)</term>
+       <listitem>
+        <para>
+	  When <varname>redirect_stderr</> is enabled, this option
+          determines the directory in which log files will be created.
+	  It may be specified as an absolute path, or relative to the
+	  cluster data directory.
+         This option can only be set at server start or in the
+         <filename>postgresql.conf</filename> configuration file.
+        </para>
+       </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-log-filename-prefix" xreflabel="log_filename_prefix">
+      <term><varname>log_filename_prefix</varname> (<type>string</type>)</term>
+       <listitem>
+        <para>
+	  When <varname>redirect_stderr</> is enabled, this option
+          sets the prefix of the file names of the created log files.
+	  The postmaster PID and the current time are appended to this
+	  prefix to form an exact log file name.
+         This option can only be set at server start or in the
+         <filename>postgresql.conf</filename> configuration file.
+        </para>
+       </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-log-rotation-age" xreflabel="log_rotation_age">
+      <term><varname>log_rotation_age</varname> (<type>integer</type>)</term>
+       <listitem>
+        <para>
+	  When <varname>redirect_stderr</> is enabled, this option
+	  determines the maximum lifetime of an individual log file.
+	  After this many minutes have elapsed, a new log file will
+	  be created.  Set to zero to disable time-based creation of
+	  new log files.
+         This option can only be set at server start or in the
+         <filename>postgresql.conf</filename> configuration file.
+        </para>
+       </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-log-rotation-size" xreflabel="log_rotation_size">
+      <term><varname>log_rotation_size</varname> (<type>integer</type>)</term>
+       <listitem>
+        <para>
+	  When <varname>redirect_stderr</> is enabled, this option
+	  determines the maximum size of an individual log file.
+	  After this many kilobytes have been emitted into a log file,
+	  a new log file will be created.  Set to zero to disable size-based
+	  creation of new log files.
+         This option can only be set at server start or in the
+         <filename>postgresql.conf</filename> configuration file.
+        </para>
+       </listitem>
+     </varlistentry>
+
      <varlistentry id="guc-syslog-facility" xreflabel="syslog_facility">
       <term><varname>syslog_facility</varname> (<type>string</type>)</term>
        <listitem>
         <para>
-          If logging to <application>syslog</> is enabled, this option
+          When logging to <application>syslog</> is enabled, this option
           determines the <application>syslog</application>
           <quote>facility</quote> to be used.  You may choose
           from <literal>LOCAL0</>, <literal>LOCAL1</>,
@@ -1826,7 +1902,7 @@ SET ENABLE_SEQSCAN TO OFF;
       <term><varname>syslog_ident</varname> (<type>string</type>)</term>
        <listitem>
         <para>
-         If logging to <application>syslog</> is enabled, this option
+         When logging to <application>syslog</> is enabled, this option
          determines the program name used to identify
          <productname>PostgreSQL</productname> messages in
          <application>syslog</application> logs. The default is