You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rp...@apache.org on 2016/09/09 17:10:10 UTC
logging-log4j2 git commit: LOG4J2-1349 updated the user manual to
document the context data injector and garbage-free ThreadContext map
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 <rp...@apache.org>
Authored: Sat Sep 10 02:10:11 2016 +0900
Committer: rpopma <rp...@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>