log4shib::NDC(3)

💖 log4shib::NDC(3) — nested diagnostic contexts, bestie 💖

Up top: this is the log4shib::NDC(3) page, from the Library Functions Manual. We’re getting into nested diagnostic contexts, and it’s honestly giving “server logs but make them make sense” energy 💅

---

🎀 NAME 🎀

log4shib::NDC — The NDC class implements nested diagnostic contexts as defined by Neil Harrison in the article "Patterns for LoggingDiagnostic Messages" part of the book Pattern Languages ofProgram Design 3 edited by Martin et al.

---

✨ SYNOPSIS ✨

#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.
• static ContextStack * cloneStack () — Clone the diagnostic context for the current thread.
• static const std::string & get () — Get the current diagnostic context string.
• static int getDepth () — Get the current nesting depth of this diagnostic context.
• static void inherit (ContextStack *stack) — no extra description in the synopsis, just the signature 🫶
• static std::string pop () — Clients should call this method before leaving a diagnostic context.
• static void push (const std::string &message) — Push new diagnostic context information for the current thread.
• static void setMaxDepth (int maxDepth) — Set the maximum nesting depth for the current NDC.
• static NDC & getNDC () — Return the NDC for the current thread.

🍓 Public Attributes

• ContextStack _stack

---

🌸 Detailed Description 🌸

The NDC class implements nested diagnostic contexts as defined by Neil Harrison in the article "Patterns for LoggingDiagnostic Messages" part of the book Pattern Languages ofProgram Design 3 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. That’s the whole tea, bestie 😭

---

🧵 Member Typedef Documentation 🧵

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

---

🎬 Constructor & Destructor Documentation 🎬

• log4shib::NDC::NDC ()
• log4shib::NDC::~NDC () [virtual]

---

💫 Member Function Documentation 💫

Virtual member functions — the underscore squad 💅

• void log4shib::NDC::_clear () [virtual]
• NDC::ContextStack * log4shib::NDC::_cloneStack () [virtual]
• const std::string & log4shib::NDC::_get () const [virtual]
• int log4shib::NDC::_getDepth () const [virtual]
• void log4shib::NDC::_inherit (NDC::ContextStack * stack) [virtual]
• std::string log4shib::NDC::_pop () [virtual]
• void log4shib::NDC::_push (const std::string & message) [virtual]
• void log4shib::NDC::_setMaxDepth (int maxDepth) [virtual]

🧚 clear — static

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 — static

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 — static

const std::string & log4shib::NDC::get () [static]

Get the current diagnostic context string.

Returns — the context string.

💜 getDepth — static

int log4shib::NDC::getDepth () [static]

Get the current nesting depth of this diagnostic context.

Returns — the nesting depth

👑 getNDC — static

NDC & log4shib::NDC::getNDC () [static]

Return the NDC for the current thread.

Returns — the NDC for the current thread

🫶 inherit — static

void log4shib::NDC::inherit (NDC::ContextStack * stack) [static]

No extra description on the page, just the signature, bestie 🫶

🍓 pop — static

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 — static

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 — static

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 🗂️

• ContextStack log4shib::NDC::_stack

---

🧚 Author 🧚

Generated automatically by Doxygen for log4shib from the source code.

---

That’s the whole page, bestie 🫶 Footer check: source log4shib, version Version 2.0.1, page log4shib::NDC(3). The footer has no separate date line, so date: not shown — and we’re not making one up 💅✨