Working with Components and Contexts

C and C++ API Overview, Components and Contexts Overview, Samples

A log message’s component and context are set when the message is created with a logging call. Messages are grouped by component and context primarily for organizational use in the viewer but also for prefiltering control in code. Both can be used to exclude certain message types and disable or secure entire groupings of log messages.

Components and contexts can be passed to logging calls either explicitly on the call or implicitly through previously established per module or per thread defaults. The use of default components and contexts is supported so that pointers do not have to be explicitly passed to every logging call or to every helper function that may do some logging on behalf of its caller. Defaults may be set at either the module or thread level. (Note that module level defaults are per process per module.) The typical usage is to have all logging out of a particular module under a single component but each thread in that module logging under a unique context. E.g. logging code in a hypothetical DBServer.exe is likely to unilaterally use ‘Database Server’ for the component but have each thread in the process set its context to a thread-unique transaction id or similar. Module and thread defaults can be pushed, popped, or changed at any time and can always be overidden by explicitly passing the component and/or context as necessary. If a component or context is not provided via explicit argument and there is no thread or module default then an internal default is used which contains blank strings, no filtering, and no security. The order of precedence is explicit, thread, module, internal.

The structures, functions, and classes for working with components and contexts are listed below:

PB_COMPONENT

PB_CONTEXT

Component structure used in the C API.

Context structure used in the C API.

PBSetComponent

PBSetContext

Used to modify component structures in a thread safe manner.

Used to modify context structures in a thread safe manner.

PBSetDefaultComponent

PBSetDefaultContext

Used to set components as thread or module defaults.

Used to set contexts as thread or module defaults.

CPBComponent

CPBContext

C++ wrapper that bundles the component functionality in the C API.

C++ wrapper that bundles the context functionality in the C API.