LOG4J2-1297 improved Configuration section, removed Socket Appender from supported list
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/8e775207 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/8e775207 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/8e775207 Branch: refs/heads/LOG4J2-1356 Commit: 8e775207091202de6b91143ad6c9421987e659ad Parents: 23e6b06 Author: rpopma <[email protected]> Authored: Thu Apr 7 02:50:51 2016 +0900 Committer: rpopma <[email protected]> Committed: Thu Apr 7 02:50:51 2016 +0900 ---------------------------------------------------------------------- src/site/xdoc/manual/garbagefree.xml | 76 +++++++++++++++++++------------ 1 file changed, 47 insertions(+), 29 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/8e775207/src/site/xdoc/manual/garbagefree.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/garbagefree.xml b/src/site/xdoc/manual/garbagefree.xml index 7154f38..8ec4755 100644 --- a/src/site/xdoc/manual/garbagefree.xml +++ b/src/site/xdoc/manual/garbagefree.xml @@ -79,6 +79,45 @@ <a name="Enable" /> <subsection name="Enabling Garbage-free Logging"> + <a name="Config" /> + <subsubsection name="Configuration"> + <h4>Configuration</h4> + <p> + In Log4j 2.6, garbage-free logging is enabled by default, except in web applications. + Log4j will partially disable garbage-free logging if it detects that it is used in a web application + (when the <tt>javax.servlet.Servlet</tt> class is in the classpath, + or when system property <tt>log4j2.is.webapp</tt> is set to "true"). + This is because garbage-free logging uses a number of ThreadLocal fields, which can cause + memory leaks when a thread pool of the web application server continues to hold references + to these fields after the web application is undeployed. + </p> + <p> + However, converting log events to text and text to bytes can be done without ThreadLocals, + so while logging is not completely garbage-free for web applications yet, + the pressure on the garbage collector can be significantly reduced. + </p> + <p> + There are two separate system properties for manually disabling the two mechanisms Log4j uses to avoid + creating temporary objects: + </p> + <ul> + <li><tt>log4j2.enable.threadlocals</tt> - if "true" (the default for non-web applications) + objects are stored in ThreadLocal fields and reused, otherwise new + objects are created for each log event</li> + <li><tt>log4j2.enable.direct.encoders</tt> - if "true" (the default) log events are converted to text and this + text is converted to bytes without creating temporary objects. Caution: multi-threaded applications + that use synchronous logging may see worse performance: the lock that was previously only around the + IO operation is widened to include the text formatting and conversion to bytes. + </li> + </ul> + <p> + Instead of system properties, the above properties can also be specified in a file named + <tt>log4j2.component.properties</tt> by including this file in the classpath of the application. + </p> + <table><tr><td><b>Caution:</b> as of version 2.6, a Log4j configuration containing a <tt><Properties></tt> section + will result in temporary objects being created during steady-state logging. + </td></tr></table> + </subsubsection> <a name="Appenders" /> <subsubsection name="Supported Appenders"> <h4>Supported Appenders</h4> @@ -92,7 +131,6 @@ <li>RandomAccessFile</li> <li>RollingRandomAccessFile (some temporary objects are created during file rollover)</li> <li>MemoryMappedFile</li> - <li>Socket</li> </ul> <p> Any other appenders not in the above list (including Async) create temporary objects during steady-state @@ -108,7 +146,7 @@ Format modifiers to control such things as field width, padding, left and right justification will not generate garbage. </p> - <table style="width: 60%"> + <table style="width: 80%"> <tr> <th>Conversion Pattern</th> <th>Description</th> @@ -211,12 +249,13 @@ </tr> </table> <p> - Logging Exceptions and stack traces will create temporary objects. - </p> - <p> Other PatternLayout conversion patterns, and other Layouts may be updated to avoid creating temporary objects in future releases. (Patches welcome!) </p> + <p> + We haven't figured out a way to log Exceptions and stack traces without creating temporary objects. + That is unfortunate, but you probably still want to log them when they happen. + </p> <table><tr><td><b>Caution:</b> patterns containing regular expressions and lookups for property substitution will result in temporary objects being created during steady-state logging. <p> @@ -280,35 +319,14 @@ public void garbageFree() { <p> </p> </subsection> - <a name="Config" /> - <subsubsection name="Configuration"> - <h4>Configuration</h4> - <p> - In Log4j 2.6, garbage-free logging is enabled by default, except in web applications. - Log4j will disable garbage-free logging if it detects that it is used in a web application - (either when the <tt>javax.servlet.Servlet</tt> class - is in the classpath or when the <tt>log4j2.is.webapp</tt> system property is set to "true"). - This is because garbage-free logging uses a number of ThreadLocal fields, which can cause - memory leaks when a thread pool of the web application server continues to hold references - to these fields after the web application is undeployed. - </p> - <p> - It is possible to manually disable garbage-free logging by setting system property - <tt>log4j2.enable.threadlocals</tt> to "false" before Log4j is initialized. - </p> - <p> - Instead of system properties, the above properties can also be specified in a file named - <tt>log4j2.component.properties</tt> by including this file in the classpath of the application. - </p> - <table><tr><td><b>Caution:</b> as of version 2.6, a Log4j configuration containing a <tt><Properties></tt> section - will result in temporary objects being created during steady-state logging. - </td></tr></table> - </subsubsection> <a name="Performance" /> <subsection name="Performance"> <a name="Latency" /> <h4>TBD what to include here</h4> + <p>Async Loggers 2.5 vs 2.6 in garbage-free mode</p> + <p>Log4j 2.6 synchronous logging "classic" versus garbage-free mode - impact of adding threads</p> + <p>Comparison with other logging libraries?</p> </subsection> <a name="UnderTheHood" /> <subsection name="Under the Hood">
