LOG4J2-1297 documentation update: added section on the API changes
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/14e850b8 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/14e850b8 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/14e850b8 Branch: refs/heads/LOG4J2-1356 Commit: 14e850b8e6d1b8144bf1ea316425171ad32f85d6 Parents: fc79e8b Author: rpopma <[email protected]> Authored: Fri Apr 8 00:44:06 2016 +0900 Committer: rpopma <[email protected]> Committed: Fri Apr 8 00:44:06 2016 +0900 ---------------------------------------------------------------------- src/site/site.xml | 19 ++++++----- src/site/xdoc/manual/garbagefree.xml | 55 ++++++++++++++++++++++++++----- 2 files changed, 56 insertions(+), 18 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/14e850b8/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index 2b92290..71819c2 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -166,6 +166,16 @@ <item name="Under The Hood" href="/manual/async.html#UnderTheHood"/> </item> + <item name="Garbage-free Logging" href="/manual/garbagefree.html" collapse="true"> + <item name="Configuration" href="/manual/garbagefree.html#Config"/> + <item name="Supported Appenders" href="/manual/garbagefree.html#Appenders"/> + <item name="Supported Layouts" href="/manual/garbagefree.html#Layouts"/> + <item name="API Changes" href="/manual/garbagefree.html#api"/> + <item name="Impact on Application Code" href="/manual/garbagefree.html#codeImpact"/> + <item name="Performance" href="/manual/garbagefree.html#Performance"/> + <item name="Under the Hood" href="/manual/garbagefree.html#UnderTheHood"/> + </item> + <item name="JMX" href="/manual/jmx.html"/> <item name="Logging Separation" href="/manual/logsep.html"/> @@ -209,15 +219,6 @@ <item name="Code Generation Tool" href="/manual/customloglevels.html#CodeGen"/> </item> - <item name="Garbage-free Logging" href="/manual/garbagefree.html" collapse="true"> - <item name="Configuration" href="/manual/garbagefree.html#Config"/> - <item name="Supported Appenders" href="/manual/garbagefree.html#Appenders"/> - <item name="Supported Layouts" href="/manual/garbagefree.html#Layouts"/> - <item name="Impact on Application Code" href="/manual/garbagefree.html#codeImpact"/> - <item name="Performance" href="/manual/garbagefree.html#Performance"/> - <item name="Under the Hood" href="/manual/garbagefree.html#UnderTheHood"/> - </item> - </menu> <menu name="Components" inherit="top" img="icon-cog"> http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/14e850b8/src/site/xdoc/manual/garbagefree.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/garbagefree.xml b/src/site/xdoc/manual/garbagefree.xml index 8ec4755..2338d1e 100644 --- a/src/site/xdoc/manual/garbagefree.xml +++ b/src/site/xdoc/manual/garbagefree.xml @@ -89,15 +89,20 @@ 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. + to these fields after the web application is undeployed. Log4j will not use these ThreadLocals + to avoid memory leaks when used in web applications. </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. + Some garbage-reducing functionality in Log4j is available for all applications: + in Log4j 2.6, converting log events to text and text to bytes can be done by directly encoding text + into a reused ByteBuffer without creating intermediary + Strings, char arrays and byte arrays. This functionality does not rely on ThreadLocals and is + enabled by default. + So while logging is not completely garbage-free for web applications yet, + the pressure on the garbage collector can still be significantly reduced. </p> <p> - There are two separate system properties for manually disabling the two mechanisms Log4j uses to avoid + There are two separate system properties for manually disabling the mechanisms Log4j uses to avoid creating temporary objects: </p> <ul> @@ -272,6 +277,27 @@ </td></tr></table> </subsubsection> + <a name="api" /> + <subsubsection name="API Changes"> + <h4>API Changes</h4> + <p> + Methods have been added to the <tt>Logger</tt> interface so that no vararg array objects are created + when logging messages with up to ten parameters. + </p> + <p> + Also, methods have been added to the <tt>Logger</tt> interface to log <tt>CharSequence</tt> messages. + User-defined objects that implement the <tt>CharSequence</tt> interface can be logged without creating + temporary objects: Log4j will try to turn CharSequence messages, + Object messages and message parameters + into text by appending them to a StringBuilder as a CharSequence. + This avoids calling <tt>toString()</tt> on these objects. + </p> + <p> + (Note that Log4j may call <tt>toString()</tt> on message and parameter objects when + garbage-free logging is disabled + because system property <tt>log4j2.enable.threadlocals</tt> is set to "false".) + </p> + </subsubsection> <a name="codeImpact" /> <subsubsection name="Impact on Application Code: Autoboxing"> <h4>Impact on Application Code: Autoboxing</h4> @@ -331,8 +357,14 @@ public void garbageFree() { <a name="UnderTheHood" /> <subsection name="Under the Hood"> <p> + Custom Message implementations that implement <tt>org.apache.logging.log4j.util.StringBuilderFormattable</tt> + can be converted to text by PatternLayout without creating temporary objects. + Other layouts that convert LogEvents to text will likely also look for this interface. + </p> + <p> Custom Layouts that want to be garbage-free should implement the <tt>Encoder<LogEvent></tt> interface. - The <tt>TextEncoder</tt> class may be useful for custom Layouts that convert a LogEvent to a text + The <tt>org.apache.logging.log4j.core.layout.TextEncoder</tt> class may be useful for custom + Layouts that convert a LogEvent to a text representation. </p> <p> @@ -340,9 +372,14 @@ public void garbageFree() { <tt>ByteBufferDestination</tt> implementation that the Layout can directly write into. </p> <p> - Custom Message implementations that implement <tt>org.apache.logging.log4j.util.StringBuilderFormattable</tt> - can be converted to text by PatternLayout without creating temporary objects. - Other layouts that convert LogEvents to text will likely also look for this interface. + <tt>AbstractOutputStreamAppender</tt> has been modified to make the ConsoleAppender, (Rolling)FileAppender, + (Rolling)RandomAccessFileAppender and MemoryMappedFileAppender garbage-free. + An effort has been made to minimize impact on custom Appenders that extend + <tt>AbstractOutputStreamAppender</tt>, but it is impossible to guarantee that changing the superclass + will not impact any and all subclasses. Custom Appenders that extend + <tt>AbstractOutputStreamAppender</tt> should verify that they still function correctly. + In case there is a problem, system property <tt>log4j2.enable.direct.encoders</tt> can be set to "false" + to revert to the pre-Log4j 2.6 behaviour. </p> <!-- <p>
