Repository: logging-log4j2 Updated Branches: refs/heads/LOG4J2-1349-gcfree-threadcontext e8a25a97c -> 7c1406ce5
LOG4J2-1349 updated the user manual to document the context data injector and garbage-free ThreadContext map Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/7c1406ce Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/7c1406ce Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/7c1406ce Branch: refs/heads/LOG4J2-1349-gcfree-threadcontext Commit: 7c1406ce5920cdee4f523a50c1e956156539c1ba Parents: e8a25a9 Author: rpopma <rpo...@apache.org> Authored: Sat Sep 10 02:10:11 2016 +0900 Committer: rpopma <rpo...@apache.org> Committed: Sat Sep 10 02:10:11 2016 +0900 ---------------------------------------------------------------------- src/site/site.xml | 1 + src/site/xdoc/manual/configuration.xml.vm | 14 ++++++++++++++ src/site/xdoc/manual/extending.xml | 16 ++++++++++++++++ src/site/xdoc/manual/garbagefree.xml | 6 +++++- src/site/xdoc/manual/thread-context.xml | 16 ++++++++++++++++ 5 files changed, 52 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7c1406ce/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index cf289e8..971e444 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -205,6 +205,7 @@ <item name="Layouts" href="/manual/extending.html#Layouts"/> <item name="PatternConverters" href="/manual/extending.html#PatternConverters"/> <item name="Plugin Builders" href="/manual/extending.html#Plugin_Builders"/> + <item name="Custom ContextDataInjector" href="/manual/extending.html#Custom_ContextDataInjector"/> <item name="Custom Plugins" href="/manual/extending.html#Custom_Plugins"/> </item> http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7c1406ce/src/site/xdoc/manual/configuration.xml.vm ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/configuration.xml.vm b/src/site/xdoc/manual/configuration.xml.vm index a7edfce..60419a4 100644 --- a/src/site/xdoc/manual/configuration.xml.vm +++ b/src/site/xdoc/manual/configuration.xml.vm @@ -1688,6 +1688,20 @@ public class AwesomeTest { </td> </tr> <tr> + <td><a name="log4j2.ContextDataInjector"/>log4j2.ContextDataInjector</td> + <td> </td> + <td> + Fully specified class name of a custom <tt>ContextDataInjector</tt> implementation class. + </td> + </tr> + <tr> + <td><a name="log4j2.garbagefree.threadContextMap"/>log4j2.garbagefree.threadContextMap</td> + <td>false</td> + <td> + Specify "true" to make the ThreadContext map garbage-free. + </td> + </tr> + <tr> <td><a name="log4j2.disable.jmx"/>log4j2.disable.jmx</td> <td>false</td> <td> http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7c1406ce/src/site/xdoc/manual/extending.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/extending.xml b/src/site/xdoc/manual/extending.xml index 2bcdef2..fae89a5 100644 --- a/src/site/xdoc/manual/extending.xml +++ b/src/site/xdoc/manual/extending.xml @@ -516,6 +516,22 @@ ListAppender list1 = ListAppender.createAppender("List1", true, false, null, nul ListAppender list2 = ListAppender.newBuilder().setName("List1").setEntryPerNewLine(true).build(); ]]></pre> </subsection> + <subsection name="Custom ContextDataInjector"> + <p> + The <code>ContextDataInjector</code> (introduced in Log4j 2.7) is responsible for + populating the LogEvent's <code>ContextData</code> with key-value pairs + or replacing it completely. + The default implementation is ThreadContextDataInjector, which obtains context attributes from the ThreadContext. + </p><p> + Applications may replace the default ContextDataInjector by setting the value of the system property + log4j2.ContextDataInjector to the name of the custom ContextDataInjector class. + </p><p> + Implementors should be aware there are some subtleties related to thread-safety and implementing a + context data injector in a garbage-free manner. + See the <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/impl/ContextDataInjector.html">ContextDataInjector</a> + javadoc for detail. + </p> + </subsection> <subsection name="Custom Plugins"> <p>See the <a href="plugins.html">Plugins</a> section of the manual.</p> <!-- TODO: some documentation here! --> http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7c1406ce/src/site/xdoc/manual/garbagefree.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/garbagefree.xml b/src/site/xdoc/manual/garbagefree.xml index 46499d5..fb683fe 100644 --- a/src/site/xdoc/manual/garbagefree.xml +++ b/src/site/xdoc/manual/garbagefree.xml @@ -133,6 +133,8 @@ synchronization on the shared buffer. If your application is multi-threaded and logging performance is important, consider using Async Loggers. </li> + <li>The ThreadContext map is <em>not</em> garbage-free by default, but from Log4j 2.7 it can be configured + to be garbage-free by setting system property <tt>log4j2.garbagefree.threadContextMap</tt> to "true".</li> </ul> <p> Instead of system properties, the above properties can also be specified in a file named @@ -355,7 +357,9 @@ public void garbageFree() { <b>Note:</b> not all logging is garbage free. Specifically: </p> <ul> - <li>The ThreadContext map and stack are not garbage-free yet.</li> + <li>The ThreadContext map is not garbage-free by default, but can be configured to be garbage-free + by setting system property <tt>log4j2.garbagefree.threadContextMap</tt> to "true".</li> + <li>The ThreadContext stack is not garbage-free.</li> <li>Logging more than 10 parameters creates vararg arrays.</li> <li>Logging very large messages (more than 518 characters) when all loggers are Async Loggers will cause the internal StringBuilder in the RingBuffer to be trimmed back to their max size. http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7c1406ce/src/site/xdoc/manual/thread-context.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/thread-context.xml b/src/site/xdoc/manual/thread-context.xml index 316de96..5ca874f 100644 --- a/src/site/xdoc/manual/thread-context.xml +++ b/src/site/xdoc/manual/thread-context.xml @@ -167,6 +167,22 @@ try (final CloseableThreadContext.Instance ctc = CloseableThreadContext.put("id" Use <code>%x</code> to include the full contents of the <a href="http://docs.oracle.com/javase/6/docs/api/java/util/Stack.html">Stack</a>. </li> </ul> + <h4>Non thread-local context data </h4> + <p> + The ThreadContext allows us to tag logging statements so we can link log entries that were related + in some way. The limitation is that this only works for logging done on the same application thread + (or child threads when configured). + </p> + <p> + Some applications have a thread model that delegates work to other threads, and + in such models, tagging attributes that are put into a thread-local map in one thread are not visible + in the other threads and logging done in the other threads will not show these attributes. + </p> + <p> + Log4j 2.7 adds a flexible mechanism to tag logging statements with context data coming from + other sources than the ThreadContext. + See the manual page on <a href="extending.html#Custom_ContextDataInjector">extending Log4j</a> for details. + </p> </subsection> </section> </body>