ScopedLoggingContext

A user facing API for creating and modifying scoped logging contexts in applications.

Scoped contexts provide a way for application code to attach metadata and control the behaviour of logging within well defined contexts. This is most often associated with making "per request" modifications to logging behaviour such as:

• Adding a request ID to every log statement.
• Forcing logging at a finer level for a specific request (e.g. based on a URL debug parameter).

Contexts are nestable and new contexts can be added to provide additional metadata which will be available to logging as long as the context is installed.

Note that in the current API contexts are also modifiable after creation, but this usage is discouraged and may be removed in future. The problem with modifying contexts after creation is that, since contexts can be shared between threads, it is potentially confusing if tags are added to a context when it is being used concurrently by multiple threads.

Note that since logging contexts are designed to be modified by code in libraries and helper functions which do not know about each other, the data structures and behaviour of logging contexts are carefully designed to avoid any accidental "undoing" of existing behaviour. In particular:

• Tags can only be added to contexts, never modified or removed.
• Logging that's enabled by one context cannot be disabled from within a nested context.

One possibly surprising result of this behaviour is that it's not possible to disable logging from within a context. However this is quite intentional, since overly verbose logging should be fixed by other mechanisms (code changes, global logging configuration), and not on a "per request" basis.

Depending on the framework used, it's possible that the current logging context will be automatically propagated to some or all threads or sub-tasks started from within the context. This is not guaranteed however and the semantic behaviour of context propagation is not defined by this class.

In particular, if you haven't explicitly opened a context in which to run your code, there is no guarantee that a default "global" context exists. In this case any attempts to add metadata (e.g. via addTags) will fail, returning false.

Context support and automatic propagation is heavily reliant on Java platform capabilities, and precise behaviour is likely to differ between runtime environments or frameworks. Context propagation may not behave the same everywhere, and in some situations logging contexts may not be supported at all. Methods which attempt to affect context state may do nothing in some environments, or when called at some points in an application. If application code relies on modifications to an existing, implicit logging context, it should always check the return values of any modification methods called (e.g. addTags).