1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 // Contributors: Dan Milstein
19 // Ray Millard
20
21 package org.apache.log4j;
22
23 import java.util.Hashtable;
24 import java.util.Stack;
25 import java.util.Enumeration;
26 import java.util.Vector;
27
28 import org.apache.log4j.helpers.LogLog;
29
30 /**
31 The NDC class implements <i>nested diagnostic contexts</i> as
32 defined by Neil Harrison in the article "Patterns for Logging
33 Diagnostic Messages" part of the book "<i>Pattern Languages of
34 Program Design 3</i>" edited by Martin et al.
35
36 <p>A Nested Diagnostic Context, or NDC in short, is an instrument
37 to distinguish interleaved log output from different sources. Log
38 output is typically interleaved when a server handles multiple
39 clients near-simultaneously.
40
41 <p>Interleaved log output can still be meaningful if each log entry
42 from different contexts had a distinctive stamp. This is where NDCs
43 come into play.
44
45 <p><em><b>Note that NDCs are managed on a per thread
46 basis</b></em>. NDC operations such as {@link #push push}, {@link
47 #pop}, {@link #clear}, {@link #getDepth} and {@link #setMaxDepth}
48 affect the NDC of the <em>current</em> thread only. NDCs of other
49 threads remain unaffected.
50
51 <p>For example, a servlet can build a per client request NDC
52 consisting the clients host name and other information contained in
53 the the request. <em>Cookies</em> are another source of distinctive
54 information. To build an NDC one uses the {@link #push push}
55 operation. Simply put,
56
57 <p><ul>
58 <li>Contexts can be nested.
59
60 <p><li>When entering a context, call <code>NDC.push</code>. As a
61 side effect, if there is no nested diagnostic context for the
62 current thread, this method will create it.
63
64 <p><li>When leaving a context, call <code>NDC.pop</code>.
65
66 <p><li><b>When exiting a thread make sure to call {@link #remove
67 NDC.remove()}</b>.
68 </ul>
69
70 <p>There is no penalty for forgetting to match each
71 <code>push</code> operation with a corresponding <code>pop</code>,
72 except the obvious mismatch between the real application context
73 and the context set in the NDC.
74
75 <p>If configured to do so, {@link PatternLayout} and {@link
76 TTCCLayout} instances automatically retrieve the nested diagnostic
77 context for the current thread without any user intervention.
78 Hence, even if a servlet is serving multiple clients
79 simultaneously, the logs emanating from the same code (belonging to
80 the same category) can still be distinguished because each client
81 request will have a different NDC tag.
82
83 <p>Heavy duty systems should call the {@link #remove} method when
84 leaving the run method of a thread. This ensures that the memory
85 used by the thread can be freed by the Java garbage
86 collector. There is a mechanism to lazily remove references to dead
87 threads. In practice, this means that you can be a little sloppy
88 and sometimes forget to call {@link #remove} before exiting a
89 thread.
90
91 <p>A thread may inherit the nested diagnostic context of another
92 (possibly parent) thread using the {@link #inherit inherit}
93 method. A thread may obtain a copy of its NDC with the {@link
94 #cloneStack cloneStack} method and pass the reference to any other
95 thread, in particular to a child.
96
97 @author Ceki Gülcü
98 @since 0.7.0
99
100 */
101
102 public class NDC {
103
104 // The synchronized keyword is not used in this class. This may seem
105 // dangerous, especially since the class will be used by
106 // multiple-threads. In particular, all threads share the same
107 // hashtable (the "ht" variable). This is OK since java hashtables
108 // are thread safe. Same goes for Stacks.
109
110 // More importantly, when inheriting diagnostic contexts the child
111 // thread is handed a clone of the parent's NDC. It follows that
112 // each thread has its own NDC (i.e. stack).
113
114 static Hashtable ht = new Hashtable();
115
116 static int pushCounter = 0; // the number of times push has been called
117 // after the latest call to lazyRemove
118
119 // The number of times we allow push to be called before we call lazyRemove
120 // 5 is a relatively small number. As such, lazyRemove is not called too
121 // frequently. We thus avoid the cost of creating an Enumeration too often.
122 // The higher this number, the longer is the avarage period for which all
123 // logging calls in all threads are blocked.
124 static final int REAP_THRESHOLD = 5;
125
126 // No instances allowed.
127 private NDC() {}
128
129 /**
130 * Get NDC stack for current thread.
131 * @return NDC stack for current thread.
132 */
133 private static Stack getCurrentStack() {
134 if (ht != null) {
135 return (Stack) ht.get(Thread.currentThread());
136 }
137 return null;
138 }
139
140
141 /**
142 Clear any nested diagnostic information if any. This method is
143 useful in cases where the same thread can be potentially used
144 over and over in different unrelated contexts.
145
146 <p>This method is equivalent to calling the {@link #setMaxDepth}
147 method with a zero <code>maxDepth</code> argument.
148
149 @since 0.8.4c */
150 public
151 static
152 void clear() {
153 Stack stack = getCurrentStack();
154 if(stack != null)
155 stack.setSize(0);
156 }
157
158
159 /**
160 Clone the diagnostic context for the current thread.
161
162 <p>Internally a diagnostic context is represented as a stack. A
163 given thread can supply the stack (i.e. diagnostic context) to a
164 child thread so that the child can inherit the parent thread's
165 diagnostic context.
166
167 <p>The child thread uses the {@link #inherit inherit} method to
168 inherit the parent's diagnostic context.
169
170 @return Stack A clone of the current thread's diagnostic context.
171
172 */
173 public
174 static
175 Stack cloneStack() {
176 Stack stack = getCurrentStack();
177 if(stack == null)
178 return null;
179 else {
180 return (Stack) stack.clone();
181 }
182 }
183
184
185 /**
186 Inherit the diagnostic context of another thread.
187
188 <p>The parent thread can obtain a reference to its diagnostic
189 context using the {@link #cloneStack} method. It should
190 communicate this information to its child so that it may inherit
191 the parent's diagnostic context.
192
193 <p>The parent's diagnostic context is cloned before being
194 inherited. In other words, once inherited, the two diagnostic
195 contexts can be managed independently.
196
197 <p>In java, a child thread cannot obtain a reference to its
198 parent, unless it is directly handed the reference. Consequently,
199 there is no client-transparent way of inheriting diagnostic
200 contexts. Do you know any solution to this problem?
201
202 @param stack The diagnostic context of the parent thread.
203
204 */
205 public
206 static
207 void inherit(Stack stack) {
208 if(stack != null)
209 ht.put(Thread.currentThread(), stack);
210 }
211
212
213 /**
214 <font color="#FF4040"><b>Never use this method directly, use the {@link
215 org.apache.log4j.spi.LoggingEvent#getNDC} method instead</b></font>.
216 */
217 static
218 public
219 String get() {
220 Stack s = getCurrentStack();
221 if(s != null && !s.isEmpty())
222 return ((DiagnosticContext) s.peek()).fullMessage;
223 else
224 return null;
225 }
226
227 /**
228 * Get the current nesting depth of this diagnostic context.
229 *
230 * @see #setMaxDepth
231 * @since 0.7.5
232 */
233 public
234 static
235 int getDepth() {
236 Stack stack = getCurrentStack();
237 if(stack == null)
238 return 0;
239 else
240 return stack.size();
241 }
242
243 private
244 static
245 void lazyRemove() {
246 if (ht == null) return;
247
248 // The synchronization on ht is necessary to prevent JDK 1.2.x from
249 // throwing ConcurrentModificationExceptions at us. This sucks BIG-TIME.
250 // One solution is to write our own hashtable implementation.
251 Vector v;
252
253 synchronized(ht) {
254 // Avoid calling clean-up too often.
255 if(++pushCounter <= REAP_THRESHOLD) {
256 return; // We release the lock ASAP.
257 } else {
258 pushCounter = 0; // OK let's do some work.
259 }
260
261 int misses = 0;
262 v = new Vector();
263 Enumeration enumeration = ht.keys();
264 // We give up after 4 straigt missses. That is 4 consecutive
265 // inspected threads in 'ht' that turn out to be alive.
266 // The higher the proportion on dead threads in ht, the higher the
267 // chances of removal.
268 while(enumeration.hasMoreElements() && (misses <= 4)) {
269 Thread t = (Thread) enumeration.nextElement();
270 if(t.isAlive()) {
271 misses++;
272 } else {
273 misses = 0;
274 v.addElement(t);
275 }
276 }
277 } // synchronized
278
279 int size = v.size();
280 for(int i = 0; i < size; i++) {
281 Thread t = (Thread) v.elementAt(i);
282 LogLog.debug("Lazy NDC removal for thread [" + t.getName() + "] ("+
283 ht.size() + ").");
284 ht.remove(t);
285 }
286 }
287
288 /**
289 Clients should call this method before leaving a diagnostic
290 context.
291
292 <p>The returned value is the value that was pushed last. If no
293 context is available, then the empty string "" is returned.
294
295 @return String The innermost diagnostic context.
296
297 */
298 public
299 static
300 String pop() {
301 Stack stack = getCurrentStack();
302 if(stack != null && !stack.isEmpty())
303 return ((DiagnosticContext) stack.pop()).message;
304 else
305 return "";
306 }
307
308 /**
309 Looks at the last diagnostic context at the top of this NDC
310 without removing it.
311
312 <p>The returned value is the value that was pushed last. If no
313 context is available, then the empty string "" is returned.
314
315 @return String The innermost diagnostic context.
316
317 */
318 public
319 static
320 String peek() {
321 Stack stack = getCurrentStack();
322 if(stack != null && !stack.isEmpty())
323 return ((DiagnosticContext) stack.peek()).message;
324 else
325 return "";
326 }
327
328 /**
329 Push new diagnostic context information for the current thread.
330
331 <p>The contents of the <code>message</code> parameter is
332 determined solely by the client.
333
334 @param message The new diagnostic context information. */
335 public
336 static
337 void push(String message) {
338 Stack stack = getCurrentStack();
339
340 if(stack == null) {
341 DiagnosticContext dc = new DiagnosticContext(message, null);
342 stack = new Stack();
343 Thread key = Thread.currentThread();
344 ht.put(key, stack);
345 stack.push(dc);
346 } else if (stack.isEmpty()) {
347 DiagnosticContext dc = new DiagnosticContext(message, null);
348 stack.push(dc);
349 } else {
350 DiagnosticContext parent = (DiagnosticContext) stack.peek();
351 stack.push(new DiagnosticContext(message, parent));
352 }
353 }
354
355 /**
356 Remove the diagnostic context for this thread.
357
358 <p>Each thread that created a diagnostic context by calling
359 {@link #push} should call this method before exiting. Otherwise,
360 the memory used by the <b>thread</b> cannot be reclaimed by the
361 VM.
362
363 <p>As this is such an important problem in heavy duty systems and
364 because it is difficult to always guarantee that the remove
365 method is called before exiting a thread, this method has been
366 augmented to lazily remove references to dead threads. In
367 practice, this means that you can be a little sloppy and
368 occasionally forget to call {@link #remove} before exiting a
369 thread. However, you must call <code>remove</code> sometime. If
370 you never call it, then your application is sure to run out of
371 memory.
372
373 */
374 static
375 public
376 void remove() {
377 if (ht != null) {
378 ht.remove(Thread.currentThread());
379
380 // Lazily remove dead-thread references in ht.
381 lazyRemove();
382 }
383 }
384
385 /**
386 Set maximum depth of this diagnostic context. If the current
387 depth is smaller or equal to <code>maxDepth</code>, then no
388 action is taken.
389
390 <p>This method is a convenient alternative to multiple {@link
391 #pop} calls. Moreover, it is often the case that at the end of
392 complex call sequences, the depth of the NDC is
393 unpredictable. The <code>setMaxDepth</code> method circumvents
394 this problem.
395
396 <p>For example, the combination
397 <pre>
398 void foo() {
399 int depth = NDC.getDepth();
400
401 ... complex sequence of calls
402
403 NDC.setMaxDepth(depth);
404 }
405 </pre>
406
407 ensures that between the entry and exit of foo the depth of the
408 diagnostic stack is conserved.
409
410 @see #getDepth
411 @since 0.7.5 */
412 static
413 public
414 void setMaxDepth(int maxDepth) {
415 Stack stack = getCurrentStack();
416 if(stack != null && maxDepth < stack.size())
417 stack.setSize(maxDepth);
418 }
419
420 // =====================================================================
421 private static class DiagnosticContext {
422
423 String fullMessage;
424 String message;
425
426 DiagnosticContext(String message, DiagnosticContext parent) {
427 this.message = message;
428 if(parent != null) {
429 fullMessage = parent.fullMessage + ' ' + message;
430 } else {
431 fullMessage = message;
432 }
433 }
434 }
435 }
436