You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by mi...@apache.org on 2016/04/08 14:04:38 UTC
[46/50] logging-log4j2 git commit: LOG4J2-1297 documentation update:
added section on the API changes
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 <rp...@apache.org>
Authored: Fri Apr 8 00:44:06 2016 +0900
Committer: rpopma <rp...@apache.org>
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>