log4shib 2.0.0

Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
log4shib::NDC Class Reference

The NDC class implements nested diagnostic contexts 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. More...

`#include <NDC.hh>`

## Classes
struct | DiagnosticContext

## Public Types
typedef std::vector< DiagnosticContext > | ContextStack

## Public Member Functions
| NDC ()
virtual | ~NDC ()
virtual void | _clear ()
virtual ContextStack * | _cloneStack ()
virtual const std::string & | _get () const
virtual int | _getDepth () const
virtual void | _inherit (ContextStack *stack)
virtual std::string | _pop ()
virtual void | _push (const std::string &message)
virtual void | _setMaxDepth (int maxDepth)

## Static Public Member Functions
static void | clear ()
| Clear any nested disgnostic information if any. More...
static ContextStack * | cloneStack ()
| Clone the diagnostic context for the current thread. More...
static const std::string & | get ()
| Get the current diagnostic context string. More...
static int | getDepth ()
| Get the current nesting depth of this diagnostic context. More...
static void | inherit (ContextStack *stack)
static std::string | pop ()
| Clients should call this method before leaving a diagnostic context. More...
static void | push (const std::string &message)
| Push new diagnostic context information for the current thread. More...
static void | setMaxDepth (int maxDepth)
| Set the maximum nesting depth for the current NDC. More...
static NDC & | getNDC ()
| Return the NDC for the current thread. More...

## Public Attributes
ContextStack | _stack

## Detailed Description

The NDC class implements nested diagnostic contexts 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.

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

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 `push`, `pop`, `clear`, `getDepth` and `setMaxDepth` affect the NDC of the current thread only. NDCs of other threads remain unaffected.

To build an NDC one uses the `push` operation. Simply put,

- Contexts can be nested.

- When entering a context, call `NDC.push`. 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 `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.

Custom Layouts may include the nested diagnostic context for the current thread in log messages, without any user intervention. Hence, even if a server 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.

Unfortunately, unlike Java, C++ does not have platform independent multithreading support. Therefore, currently log4shib is not multithread aware, it implicitly assumes only one thread exists, the main process thread.

## Member Typedef Documentation

## ◆ ContextStack

typedef std::vector<DiagnosticContext> log4shib::NDC::ContextStack

## Constructor & Destructor Documentation

## ◆ NDC()

log4shib::NDC::NDC | ( |  | ) |

## ◆ ~NDC()

log4shib::NDC::~NDC | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ _clear()

void log4shib::NDC::_clear | ( |  | ) |
| virtual

## ◆ _cloneStack()

NDC::ContextStack * log4shib::NDC::_cloneStack | ( |  | ) |
| virtual

## ◆ _get()

const std::string & log4shib::NDC::_get | ( |  | ) | const
| virtual

## ◆ _getDepth()

int log4shib::NDC::_getDepth | ( |  | ) | const
| virtual

## ◆ _inherit()

void log4shib::NDC::_inherit | ( | NDC::ContextStack * | stack | ) |
| virtual

## ◆ _pop()

std::string log4shib::NDC::_pop | ( |  | ) |
| virtual

## ◆ _push()

void log4shib::NDC::_push | ( | const std::string & | message | ) |
| virtual

## ◆ _setMaxDepth()

void log4shib::NDC::_setMaxDepth | ( | int | maxDepth | ) |
| virtual

## ◆ clear()

void log4shib::NDC::clear | ( |  | ) |
| static

Clear any nested disgnostic 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 `setMaxDepth` method with a zero `maxDepth` argument.

## ◆ cloneStack()

NDC::ContextStack * log4shib::NDC::cloneStack | ( |  | ) |
| static

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 `inherit` method to inherit the parent's diagnostic context.

Returns
  Stack A clone of the current thread's diagnostic context.

## ◆ get()

const std::string & log4shib::NDC::get | ( |  | ) |
| static

Get the current diagnostic context string.

Returns
  the context string.

## ◆ getDepth()

int log4shib::NDC::getDepth | ( |  | ) |
| static

Get the current nesting depth of this diagnostic context.

Returns
  the nesting depth

## ◆ getNDC()

NDC & log4shib::NDC::getNDC | ( |  | ) |
| static

Return the NDC for the current thread.

Returns
  the NDC for the current thread

## ◆ inherit()

void log4shib::NDC::inherit | ( | NDC::ContextStack * | stack | ) |
| static

## ◆ pop()

std::string log4shib::NDC::pop | ( |  | ) |
| static

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.

Returns
  String The innermost diagnostic context.

## ◆ push()

void log4shib::NDC::push | ( | const std::string & | message | ) |
| static

Push new diagnostic context information for the current thread.

The contents of the `message` parameter is determined solely by the client.

Parameters

  message | The new diagnostic context information.

## ◆ setMaxDepth()

void log4shib::NDC::setMaxDepth | ( | int | maxDepth | ) |
| static

Set the maximum nesting depth for the current NDC.

Curently NDCs do not enforce a maximum depth and consequentially this method has no effect.

Parameters

  maxDepth | the maximum nesting depth

## Member Data Documentation

## ◆ _stack

ContextStack log4shib::NDC::_stack

The documentation for this class was generated from the following files:

- NDC.hh
- NDC.cpp