Improved docs for LoggerAppenderDailyFile
authorIvan Habunek <ihabunek@apache.org>
Sat, 6 Oct 2012 06:21:41 +0000 (06:21 +0000)
committerIvan Habunek <ihabunek@apache.org>
Sat, 6 Oct 2012 06:21:41 +0000 (06:21 +0000)
git-svn-id: https://svn.apache.org/repos/asf/logging/log4php/trunk@1394939 13f79535-47bb-0310-9956-ffa450edef68

src/site/xdoc/docs/appenders/daily-file.xml

index b27f6d8..4f5d352 100644 (file)
        <body>\r
                <section name="LoggerAppenderDailyFile">\r
                \r
-                       <p><code>LoggerAppenderDailyFile</code> writes logging events to a file. The file is rolled over \r
-                       once a day. In other words, for each day a new file is created.</p>\r
+                       <p><code>LoggerAppenderDailyFile</code> writes logging events to a file which is rolled over depending on \r
+                       the date/time of the logging event. By default, the file is rolled over daily, hence the appender name. \r
+                       However, the appender can just as easily be configured to roll over once a month, or even every minute \r
+                       if desired.</p>\r
                        \r
-                       <p>The path specified in the <code>file</code> parameter string should contain the string <code>%s</code> \r
-                       which will be substituted with the current date when logging. The <code>datePattern</code> parameter \r
-                       determines how the date will be formatted.</p>\r
+                       <p>Unlike <code>LoggerAppenderFile</code>, the target file is not static, and can change during script \r
+                       execution as the time passes. Destination file is determined by two parameters: <code>file</code> and\r
+                       <code>datePattern</code>.</p>\r
+                       \r
+                       <p>The path specified in the <code>file</code> parameter should contain the string <code>%s</code>. \r
+                       Each time an event is logged, this string will be substituted with \r
+                       the event's date/time formatted according to <code>datePattern</code> and the event will be logged to \r
+                       the resulting file path.</p>\r
+                       \r
+                       <p>The date/time is formatted according to format string specified in the <code>datePattern</code> \r
+                       parameter. The format uses the same rules as the PHP <code><a class="external" \r
+                       href="http://php.net/manual/en/function.date.php">date()</a></code> function. Any format string supported\r
+                       by <code>date()</code> function may be used as a date pattern.</p>\r
                        \r
                        <subsection name="Layout">\r
                                <p>This appender requires a layout. If no layout is specified in configuration, \r
                                \r
                        <subsection name="Examples">\r
                                \r
-                               <p>This example shows how to configure <code>LoggerAppenderDailyFile</code>.</p>\r
-                               \r
-                               <p>The date pattern used is <code>Y-m-d</code> which will result in filenames similar to \r
-                               <code>file-2011-10-01.log</code>.</p>\r
-                               \r
+                               <p>Consider the following configuration:</p>\r
+                       \r
                                <div class="auto-tabs">\r
                                        <ul>\r
                                                <li>XML</li>\r
@@ -130,6 +139,30 @@ array(
                                                </div>\r
                                        </div>\r
                                </div>\r
+                               \r
+                               <p>In this example, the date pattern is set to <code>Y-m-d</code> (year, month, day) and the target \r
+                               file to <code>daily.%s.log</code>.</p>\r
+                               \r
+                               <p>Each time this appender receives a logging event, it will:</p>\r
+                               \r
+                               <ol>\r
+                                       <li>Format the event date/time according to the configured date pattern. Let's say this sample \r
+                                       is run during 10th of July 2012, then the formatted date is <code>2012-07-10</code></li>\r
+                                       <li>Replace the <code>%s</code> in the filename with the formated date to get the target file. \r
+                                       In this case, the target file will be <code>daily.2012-07-10.log</code>.</li>\r
+                                       <li>Write to the target file.</li>\r
+                               </ol>\r
+                               \r
+                               <p>If you continue logging using the given configuration, the appender will continue to log to \r
+                               <code>daily.2012-07-10.log</code>, until the date changes. At that point it will start logging to \r
+                               <code>daily.2012-07-11.log</code>.</p>\r
+                               \r
+                               <p>Similarly, date pattern <code>Y-m</code> will result in filenames like <code>file-2012-07.log</code>,\r
+                                which will result in monthly rollover.</p>\r
+                               \r
+                               <p>Hours, minutes and seconds can also be used. Pattern <code>Y-m-d.H.i.s</code> will result \r
+                               in filenames similar to <code>file-2012-07-03.10.37.15.log</code>. In this case, a new file will be \r
+                               created each second.</p>\r
                        </subsection>\r
                </section>\r
        </body>\r