[jira] [Created] (LOG4J2-218) Improve documentation for FileAppender and basic use cases

["Remko Popma (JIRA)" <ji...@apache.org>]

Remko Popma created LOG4J2-218:
----------------------------------

             Summary: Improve documentation for FileAppender and basic use cases
                 Key: LOG4J2-218
                 URL: https://issues.apache.org/jira/browse/LOG4J2-218
             Project: Log4j 2
          Issue Type: Improvement
          Components: Documentation
    Affects Versions: 2.0-beta5
            Reporter: Remko Popma


On the log4j-user mailing list, Peter DePasquale pointed out that with the default values for FileAppender (bufferedIO="true" and immediateFlush="false"), a small test program does not actually write to disk.

Especially for novice users this can be frustrating and hard to solve.
I propose to add a cautionary note to the docs for all appenders that are buffered.
(It is also not completely clear that the default for immediateFlush is false.)

Also, for the reason above, the example configuration in the docs don't "work out of the box".
Most users will copy the example configuration when they start with log4j2 (that's what I did...)

In order to make everyone's first impression as smooth as possible I propose we add either bufferedIO="false" or immediateFlush="true" to all relevant example configurations. 

In addition, (and people may disagree with me on this) I think the sample configurations should avoid using location-based layouts like %C, %M, %location etc. 
That is, unless the sample demonstrates the location-based capabilities, of course.
The performance impact of location-based layouts is quite large (something like 5x slower), and I'd hate to give people the first impression that log4j2 is slow because of our own example configs...

Here is the sample File configuration in http://logging.apache.org/log4j/2.x/manual/appenders.html#FileAppender with my proposed changes:

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration status="warn" name="MyApp" packages="">
    <appenders>
    <File name="MyFile" fileName="logs/app.log" immediateFlush="true">  <!-- flush -->
    <PatternLayout>
    <pattern>%d %p %c{1.} [%t] %m%n</pattern> <!-- avoid location %C in examples -->
    </PatternLayout>
    </File>
    </appenders>
    <loggers>
    <root level="error">
    <appender-ref ref="MyFile"/>
    </root>
    </loggers>
    </configuration>

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira

---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org