[
https://issues.apache.org/jira/browse/LOG4J2-218?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Remko Popma updated LOG4J2-218:
-------------------------------
Description:
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"><!-- mandatory root logger -->
<appender-ref ref="MyFile"/>
</root>
</loggers>
</configuration>
was:
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>
> 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"><!-- mandatory root logger -->
> <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]
