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: [email protected]
For additional commands, e-mail: [email protected]
