This package provides functionality for Resource Adaptors to interact with ThreadLocal stored MDC (Mapped Diagnostic Context), also known as logging context.
What is MDC
MDC is a Map<String, String> of keys and values which will are available to the logging subsystem for various purposes.
The most common and straightfoward use of MDC is printing in every log message.
This provides a mechanism for providing context to log messages that would otherwise require manually passing around.
A simple SIP example of useful context would be including the p-charging-vector header.
As this uniquely identifies a single call, it becomes trivial to identify all log messages related to handling an individual call.
By default Rhino logs the entire MDC on every log message.
Rhino provides transparent management of MDC in the event router threadpool. This is achieved by every Activity storing a copy of the creating thread’s MDC at activity creation. The activity stored context is restored to the EventRouter thread on beginning event processing.
Services (and service components) have a separate interface for managing MDC elements.
Resource Adaptors have access to this package to provide the tools necessary to manipulate MDC appropriately. RA internal ThreadPools do not have MDC transparently replicated across thread transitions by Rhino. This is the responsibility of the RA owning the ThreadPool.
Thread Boundaries
As MDC is stored in a ThreadLocal Map, it will not follow over thread boundaries.
For example, in the asynchronous API of any RA providing such, there will be an RA provided mechanism to hand off work to another thread (the handling thread).
In order for any logging done by the handling thread to log the MDC, the handoff mechanism must support this by copying the MDC
and clearing it from the handling thread when done.
What to include
As the entire MDC map is logged unconditionally with every log message human readable logs require that the MDC map be kept small. Both a small number of total entries, and the shortest practicable entires. A key should only be added to the MDC if it will provide significant value in tracking or sorting log messages,
For example, Rhino includes by default two MDC entries:
-
The current namespace (if not the default) as
ns=foo -
The current transaction ID (if present) as
txId=101:203462114705319
The included txId is used for Rhino diagnostics, to track exactly what occurred within a given SLEE transaction, at all stages. From the service code to Rhino internals of transaction handling.
Identifiers that are short lived or not meaningful outside of the RA generally should not be added to MDC at all. And certainly not in a persistent manner except in extraordinary circumstances.
As an example of an identifier that should not be added persistently consider the SLEE TransactionID. This is not persisted within the backing Activity across multiple events, as each event takes place within a single transaction. This is a rare exception where an ephemeral key makes sense to add to MDC as processing each event involves at least one transaction, and being able to track the flow of logic within a single transaction can be extremely useful in error conditions. However, the transaction ID becomes meaningless on transaction completion, weather as a commit, or rollback. The txId key is therefore removed from MDC as soon as the transaction is completed.
|
Since Rhino 2.6.0 |
