A Nested Diagnostic Context, or NDC in short, is an instrument + to distinguish interleaved log output from different sources. Log + output is typically interleaved when a server handles multiple + clients near-simultaneously. + +
Interleaved log output can still be meaningful if each log entry + from different contexts had a distinctive stamp. This is where NDCs + come into play. + +
Note that NDCs are managed on a per thread + basis. NDC operations such as {@link #push push}, {@link + #pop}, {@link #clear}, {@link #getDepth} and {@link #setMaxDepth} + affect the NDC of the current thread only. NDCs of other + threads remain unaffected. + +
For example, a servlet can build a per client request NDC + consisting the clients host name and other information contained in + the the request. Cookies are another source of distinctive + information. To build an NDC one uses the {@link #push push} + operation. Simply put, + +
NDC.push. As a
+ side effect, if there is no nested diagnostic context for the
+ current thread, this method will create it.
+
+ NDC.pop.
+
+ There is no penalty for forgetting to match each
+ push operation with a corresponding pop,
+ except the obvious mismatch between the real application context
+ and the context set in the NDC.
+
+
If configured to do so, {@link PatternLayout} and {@link + TTCCLayout} instances automatically retrieve the nested diagnostic + context for the current thread without any user intervention. + Hence, even if a servlet is serving multiple clients + simultaneously, the logs emanating from the same code (belonging to + the same category) can still be distinguished because each client + request will have a different NDC tag. + +
Heavy duty systems should call the {@link #remove} method when + leaving the run method of a thread. This ensures that the memory + used by the thread can be freed by the Java garbage + collector. There is a mechanism to lazily remove references to dead + threads. In practice, this means that you can be a little sloppy + and sometimes forget to call {@link #remove} before exiting a + thread. + +
A thread may inherit the nested diagnostic context of another + (possibly parent) thread using the {@link #inherit inherit} + method. A thread may obtain a copy of its NDC with the {@link + #cloneStack cloneStack} method and pass the reference to any other + thread, in particular to a child. + + @author Ceki Gülcü + @since 0.7.0 + +*/ + +public class NDC { + + // The synchronized keyword is not used in this class. This may seem + // dangerous, especially since the class will be used by + // multiple-threads. In particular, all threads share the same + // hashtable (the "ht" variable). This is OK since java hashtables + // are thread safe. Same goes for Stacks. + + // More importantly, when inheriting diagnostic contexts the child + // thread is handed a clone of the parent's NDC. It follows that + // each thread has its own NDC (i.e. stack). + + static Hashtable ht = new Hashtable(); + + static int pushCounter = 0; // the number of times push has been called + // after the latest call to lazyRemove + + // The number of times we allow push to be called before we call lazyRemove + // 5 is a relatively small number. As such, lazyRemove is not called too + // frequently. We thus avoid the cost of creating an Enumeration too often. + // The higher this number, the longer is the avarage period for which all + // logging calls in all threads are blocked. + static final int REAP_THRESHOLD = 5; + + // No instances allowed. + private NDC() {} + + /** + * Get NDC stack for current thread. + * @return NDC stack for current thread. + */ + private static Stack getCurrentStack() { + if (ht != null) { + return (Stack) ht.get(Thread.currentThread()); + } + return null; + } + + + /** + Clear any nested diagnostic information if any. This method is + useful in cases where the same thread can be potentially used + over and over in different unrelated contexts. + +
This method is equivalent to calling the {@link #setMaxDepth}
+ method with a zero maxDepth argument.
+
+ @since 0.8.4c */
+ public
+ static
+ void clear() {
+ Stack stack = getCurrentStack();
+ if(stack != null) {
+ stack.setSize(0);
+ }
+ }
+
+
+ /**
+ Clone the diagnostic context for the current thread.
+
+
Internally a diagnostic context is represented as a stack. A + given thread can supply the stack (i.e. diagnostic context) to a + child thread so that the child can inherit the parent thread's + diagnostic context. + +
The child thread uses the {@link #inherit inherit} method to + inherit the parent's diagnostic context. + + @return Stack A clone of the current thread's diagnostic context. + + */ + public + static + Stack cloneStack() { + Stack stack = getCurrentStack(); + if(stack == null) { + return null; + } else { + return (Stack) stack.clone(); + } + } + + + /** + Inherit the diagnostic context of another thread. + +
The parent thread can obtain a reference to its diagnostic + context using the {@link #cloneStack} method. It should + communicate this information to its child so that it may inherit + the parent's diagnostic context. + +
The parent's diagnostic context is cloned before being + inherited. In other words, once inherited, the two diagnostic + contexts can be managed independently. + +
In java, a child thread cannot obtain a reference to its + parent, unless it is directly handed the reference. Consequently, + there is no client-transparent way of inheriting diagnostic + contexts. Do you know any solution to this problem? + + @param stack The diagnostic context of the parent thread. + + */ + public + static + void inherit(Stack stack) { + if(stack != null) { + ht.put(Thread.currentThread(), stack); + } + } + + + /** + Never use this method directly, use the {@link + org.apache.log4j.spi.LoggingEvent#getNDC} method instead. + */ + static + public + String get() { + Stack s = getCurrentStack(); + if(s != null && !s.isEmpty()) { + return ((DiagnosticContext) s.peek()).fullMessage; + } else { + return null; + } + } + + /** + * Get the current nesting depth of this diagnostic context. + * + * @see #setMaxDepth + * @since 0.7.5 + */ + public + static + int getDepth() { + Stack stack = getCurrentStack(); + if(stack == null) { + return 0; + } else { + return stack.size(); + } + } + + private + static + void lazyRemove() { + if (ht == null) { + return; + } + + // The synchronization on ht is necessary to prevent JDK 1.2.x from + // throwing ConcurrentModificationExceptions at us. This sucks BIG-TIME. + // One solution is to write our own hashtable implementation. + Vector v; + + synchronized(ht) { + // Avoid calling clean-up too often. + if(++pushCounter <= REAP_THRESHOLD) { + return; // We release the lock ASAP. + } else { + pushCounter = 0; // OK let's do some work. + } + + int misses = 0; + v = new Vector(); + Enumeration enumeration = ht.keys(); + // We give up after 4 straigt missses. That is 4 consecutive + // inspected threads in 'ht' that turn out to be alive. + // The higher the proportion on dead threads in ht, the higher the + // chances of removal. + while(enumeration.hasMoreElements() && (misses <= 4)) { + Thread t = (Thread) enumeration.nextElement(); + if(t.isAlive()) { + misses++; + } else { + misses = 0; + v.addElement(t); + } + } + } // synchronized + + int size = v.size(); + for(int i = 0; i < size; i++) { + Thread t = (Thread) v.elementAt(i); + LogLog.debug("Lazy NDC removal for thread [" + t.getName() + "] ("+ + ht.size() + ")."); + ht.remove(t); + } + } + + /** + Clients should call this method before leaving a diagnostic + context. + +
The returned value is the value that was pushed last. If no + context is available, then the empty string "" is returned. + + @return String The innermost diagnostic context. + + */ + public + static + String pop() { + Stack stack = getCurrentStack(); + if(stack != null && !stack.isEmpty()) { + return ((DiagnosticContext) stack.pop()).message; + } else { + return ""; + } + } + + /** + Looks at the last diagnostic context at the top of this NDC + without removing it. + +
The returned value is the value that was pushed last. If no + context is available, then the empty string "" is returned. + + @return String The innermost diagnostic context. + + */ + public + static + String peek() { + Stack stack = getCurrentStack(); + if(stack != null && !stack.isEmpty()) { + return ((DiagnosticContext) stack.peek()).message; + } else { + return ""; + } + } + + /** + Push new diagnostic context information for the current thread. + +
The contents of the message parameter is
+ determined solely by the client.
+
+ @param message The new diagnostic context information. */
+ public
+ static
+ void push(String message) {
+ Stack stack = getCurrentStack();
+
+ if(stack == null) {
+ DiagnosticContext dc = new DiagnosticContext(message, null);
+ stack = new Stack();
+ Thread key = Thread.currentThread();
+ ht.put(key, stack);
+ stack.push(dc);
+ } else if (stack.isEmpty()) {
+ DiagnosticContext dc = new DiagnosticContext(message, null);
+ stack.push(dc);
+ } else {
+ DiagnosticContext parent = (DiagnosticContext) stack.peek();
+ stack.push(new DiagnosticContext(message, parent));
+ }
+ }
+
+ /**
+ Remove the diagnostic context for this thread.
+
+
Each thread that created a diagnostic context by calling + {@link #push} should call this method before exiting. Otherwise, + the memory used by the thread cannot be reclaimed by the + VM. + +
As this is such an important problem in heavy duty systems and
+ because it is difficult to always guarantee that the remove
+ method is called before exiting a thread, this method has been
+ augmented to lazily remove references to dead threads. In
+ practice, this means that you can be a little sloppy and
+ occasionally forget to call {@link #remove} before exiting a
+ thread. However, you must call remove sometime. If
+ you never call it, then your application is sure to run out of
+ memory.
+
+ */
+ static
+ public
+ void remove() {
+ if (ht != null) {
+ ht.remove(Thread.currentThread());
+
+ // Lazily remove dead-thread references in ht.
+ lazyRemove();
+ }
+ }
+
+ /**
+ Set maximum depth of this diagnostic context. If the current
+ depth is smaller or equal to maxDepth, then no
+ action is taken.
+
+
This method is a convenient alternative to multiple {@link
+ #pop} calls. Moreover, it is often the case that at the end of
+ complex call sequences, the depth of the NDC is
+ unpredictable. The setMaxDepth method circumvents
+ this problem.
+
+
For example, the combination +
+ void foo() {
+ int depth = NDC.getDepth();
+
+ ... complex sequence of calls
+
+ NDC.setMaxDepth(depth);
+ }
+
+
+ ensures that between the entry and exit of foo the depth of the
+ diagnostic stack is conserved.
+
+ @see #getDepth
+ @since 0.7.5 */
+ static
+ public
+ void setMaxDepth(int maxDepth) {
+ Stack stack = getCurrentStack();
+ if(stack != null && maxDepth < stack.size()) {
+ stack.setSize(maxDepth);
+ }
+ }
+
+ // =====================================================================
+ private static class DiagnosticContext {
+
+ String fullMessage;
+ String message;
+
+ DiagnosticContext(String message, DiagnosticContext parent) {
+ this.message = message;
+ if(parent != null) {
+ fullMessage = parent.fullMessage + ' ' + message;
+ } else {
+ fullMessage = message;
+ }
+ }
+ }
+}
+