svn commit: r1344155 - in /logging/log4j/trunk/src: main/java/org/apache/log4j/MDC.java site/fml/faq.fml

[gr...@apache.org]

Author: grobmeier
Date: Wed May 30 08:56:01 2012
New Revision: 1344155

URL: http://svn.apache.org/viewvc?rev=1344155&view=rev
Log:
docs for correct use of MDC (refers to 50486)

Modified:
    logging/log4j/trunk/src/main/java/org/apache/log4j/MDC.java
    logging/log4j/trunk/src/site/fml/faq.fml

Modified: logging/log4j/trunk/src/main/java/org/apache/log4j/MDC.java
URL: http://svn.apache.org/viewvc/logging/log4j/trunk/src/main/java/org/apache/log4j/MDC.java?rev=1344155&r1=1344154&r2=1344155&view=diff
==============================================================================
--- logging/log4j/trunk/src/main/java/org/apache/log4j/MDC.java (original)
+++ logging/log4j/trunk/src/main/java/org/apache/log4j/MDC.java Wed May 30 08:56:01 2012
@@ -38,7 +38,22 @@ import java.util.Hashtable;
  * <p/>
  * <p>The MDC class requires JDK 1.2 or above. Under JDK 1.1 the MDC
  * will always return empty values but otherwise will not affect or
- * harm your application.
+ * harm your application.</p>
+ *
+ * <p>Attention: the application is required to clean up. In web applications
+ * this can happen with creating a Servlet Filter and overriding the
+ * onFilter method like:</p>
+ *
+ * <pre>
+ * try {
+ *    MDC.put(myKey);
+ *    chain.doFilter(request, response);
+ * } finally {
+ *    MDC.remove(myKey);
+ * }
+ * </pre>
+ *
+ * <p>Please also see: {@link http://logging.apache.org/log4j/1.2/faq.html#mdcmemoryleak}</p>
  *
  * @author Ceki G&uuml;lc&uuml;
  * @since 1.2
@@ -162,7 +177,7 @@ public class MDC {
                 ht.remove(key);
                 // clean up if this was the last key
                 if (ht.isEmpty()) {
-                    clear0();
+                        clear0();
                 }
             }
         }

Modified: logging/log4j/trunk/src/site/fml/faq.fml
URL: http://svn.apache.org/viewvc/logging/log4j/trunk/src/site/fml/faq.fml?rev=1344155&r1=1344154&r2=1344155&view=diff
==============================================================================
--- logging/log4j/trunk/src/site/fml/faq.fml (original)
+++ logging/log4j/trunk/src/site/fml/faq.fml Wed May 30 08:56:01 2012
@@ -871,5 +871,38 @@ public class Foo {
               <p>The SMTPAppender may be influenced by mail.smtp and mail.smtps system properties.</p>
           </answer>
       </faq>
+      
+       <faq id="mdcmemoryleak">
+          <question>How can I prevent memory leaks when using MDC?</question>
+          <answer>
+          
+          The following message sometimes comes up in combination with MDC:
+          
+          <pre>
+[webapp] created a ThreadLocal with key of type [org.apache.log4j.helpers.ThreadLocalMap] (value [org.apache.log4j.helpers.ThreadLocalMap@f6af3b]) and a value of type [java.util.Hashtable] (value [{userId=jo2372}]) but failed to remove it when the web application was stopped. This is very likely to create a memory leak.
+          </pre>
+          
+          In this case MDC is not cleaned up properly. Since log4j 1.2.17 the clear()-Method is called when the last
+          key of the underlying ThreadLocalMap is removed. To prevent the error message above,
+          the application need to take care it self of removing the keys which are not longer necessary.
+          
+          With web applications one can do this with creating a Servlet Filter and overriding the doFilter method:
+          
+          <pre>
+try {
+    MDC.put(myKey);
+    chain.doFilter(request, response);
+} finally {
+    MDC.remove(myKey);
+}          
+          </pre>
+          
+          Please note, cleaning up the MDC in the Servlets destroy method might not lead to the desired results,
+          as destroy is not necessary called from the Thread which is holding the the map.
+            
+          For more information please also see: https://issues.apache.org/bugzilla/show_bug.cgi?id=50486
+      </answer>
+      </faq>
+
   </part>
 </faqs>