Improve documentation of log rotation options, per Ed L.

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 1a2f24500f3bd3b45a0c6f1602e03858cec6dffc..2ca5e38018ae839ed98f89592a2aaa0032c6113a 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 
 
 
@@ -1929,16 +1929,16 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Win32
       log_filename (string)
        
         
-          When redirect_stderr is enabled, this option
+          When redirect_stderrvarname> is enabled, this option
           sets the file names of the created log files.  The value
-          is treated as a strftime pattern,
-          so %-escapes
+          is treated as a strftimesystemitem> pattern,
+          so %literal>-escapes
           can be used to specify time-varying file names.
-          If no %-escapes are present,
+          If no %literal>-escapes are present,
           PostgreSQL will
           append the epoch of the new log file's open time.  For example,
-          if log_filename> were server_log>, then the
-          chosen file name would be server_log.1093827753
+          if log_filenamevarname> were server_log>, then the
+          chosen file name would be server_log.1093827753literal>
           for a log starting at Sun Aug 29 19:02:33 2004 MST.
          This option can only be set at server start or in the
          postgresql.conf configuration file.
@@ -1950,7 +1950,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Win32
       log_rotation_age (integer)
        
         
-          When redirect_stderr is enabled, this option
+          When redirect_stderrvarname> 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
@@ -1965,7 +1965,7 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Win32
       log_rotation_size (integer)
        
         
-          When redirect_stderr is enabled, this option
+          When redirect_stderrvarname> 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
@@ -1980,19 +1980,38 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Win32
       log_truncate_on_rotation (boolean)
        
         
-          When redirect_stderr is enabled, this option will cause
+          When redirect_stderrvarname> is enabled, this option will cause
           PostgreSQL to truncate (overwrite),
           rather than append to, any existing log file of the same name.
           However, truncation will occur only when a new file is being opened
           due to time-based rotation, not during server startup or size-based
           rotation.  When false, pre-existing files will be appended to in
           all cases.  For example, using this option in combination with
-          a log_filename> like postgresql-%H.log>
+          a log_filenamevarname> like postgresql-%H.log>
           would result in generating twenty-four hourly log files and then
           cyclically overwriting them.
          This option can only be set at server start or in the
          postgresql.conf configuration file.
         
+        
+          Example:  To keep 7 days of logs, one log file per day named
+          server_log.Mon, server_log.Tue, 
+          etc, and automatically overwrite last week's log with this week's log,
+          set log_filename to server_log.%a, 
+          log_truncate_on_rotation to true, and 
+          log_rotation_age to 1440.
+        
+        
+          Example: To keep 24 hours of logs, one log file per hour, but 
+          also rotate sooner if the log file size exceeds 1GB, set 
+          log_filename to server_log.%H%M, 
+          log_truncate_on_rotation to true, 
+          log_rotation_age to 60, and 
+          log_rotation_size to 1000000.
+          Including %M in log_filename allows
+          any size-driven rotations that may occur to select a filename
+          different from the hour's initial filename.
+