You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4j-dev@logging.apache.org by "Remko Popma (JIRA)" <ji...@apache.org> on 2013/04/27 05:42:16 UTC
[jira] [Updated] (LOG4J2-218) Improve documentation for
FileAppender and basic use cases
[ 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: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org