Class: LoggerNDC  - X-Ref

The NDC class implements <i>nested diagnostic contexts</i> as
defined by Neil Harrison in the article "Patterns for Logging
Diagnostic Messages" part of the book "<i>Pattern Languages of
Program Design 3</i>" edited by Martin et al.

<p>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.

<p>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.

<p><i><b>Note that NDCs are managed on a per thread
basis</b></i>. NDC operations such as {@link push()}, {@link pop()},
{@link clear()}, {@link getDepth()} and {@link setMaxDepth()}
affect the NDC of the <i>current</i> thread only. NDCs of other
threads remain unaffected.

<p>For example, a servlet can build a per client request NDC
consisting the clients host name and other information contained in
the the request. <i>Cookies</i> are another source of distinctive
information. To build an NDC one uses the {@link push()}
operation.</p>

Simply put,

- Contexts can be nested.
- When entering a context, call
<code>LoggerNDC::push()</code>
As a side effect, if there is no nested diagnostic context for the
current thread, this method will create it.
- When leaving a context, call
<code>LoggerNDC::pop()</code>
- <b>When exiting a thread make sure to call {@link remove()}</b>

<p>There is no penalty for forgetting to match each
<code>push</code> operation with a corresponding <code>pop</code>,
except the obvious mismatch between the real application context
and the context set in the NDC.</p>

<p>If configured to do so, {@link LoggerPatternLayout} and {@link LoggerLayoutTTCC}
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.</p>