Rewrite thread-context.adoc et al. (#2535)

Author: vy

Diff for: src/site/antora/modules/ROOT/pages/manual/api.adoc

@@ -239,7 +239,7 @@ xref:manual/logbuilder.adoc[Read more on the Fluent API...]
 [#fish-tagging]
 == Fish tagging
 
-Just as a fish can be tagged and have its movement tracked (aka. _fish tagging_), stamping log events with a common tag or set of data
+Just as a fish can be tagged and have its movement tracked (aka. _fish tagging_ footnote:[Fish tagging is first described by Neil Harrison in the _"Patterns for Logging Diagnostic Messages"_ chapter of https://dl.acm.org/doi/10.5555/273448[_"Pattern Languages of Program Design 3"_ edited by R. Martin, D. Riehle, and F. Buschmann in 1997].]), stamping log events with a common tag or set of data
 elements allows the complete flow of a transaction or a request to be tracked.
 You can use them for several purposes, such as:
 
@@ -283,7 +283,7 @@ xref:manual/markers.adoc[Read more on markers...]
 [#scoped-context]
 === Scoped Context
 
-Just like a https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/ScopedValue.html[Java's `ScopedValue`], in Scoped Context, the visibility of tags are associated with the block they were introduced:
+Just like a https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/ScopedValue.html[Java's `ScopedValue`], _Scoped Context_ facilitates associating information with a certain block of code and makings this accessible to the rest of the logging system:
 
 [source,java]
 ----
@@ -317,22 +317,36 @@ xref:manual/scoped-context.adoc[Read more on Scoped Context...]
 [#thread-context]
 === Thread Context
 
-Just like https://docs.oracle.com/javase/8/docs/api/java/lang/ThreadLocal.html[Java's `ThreadLocal`], in Thread Context, the visibility of tags are associated with the thread they were introduced.
-Thread Context offers both a map-structured, called _Mapped Diagnostic Context (MDC)_, and a stack-structured, called _Nested Diagnostic Context (NDC)_, storage:
+Just like https://docs.oracle.com/javase/8/docs/api/java/lang/ThreadLocal.html[Java's `ThreadLocal`], _Thread Context_ facilitates associating information with the executing thread and making this information accessible to the rest of the logging system.
+Thread Context offers both
+
+* map-structured – referred to as _Thread Context Map_ or _Mapped Diagnostic Context (MDC)_
+* stack-structured – referred to as _Thread Context Stack_ or _Nested Diagnostic Context (NDC)_
+
+storage:
 
 [source,java]
 ----
 ThreadContext.put("ipAddress", request.getRemoteAddr()); // <1>
 ThreadContext.put("hostName", request.getServerName()); // <1>
 ThreadContext.put("loginId", session.getAttribute("loginId")); // <1>
 
-ThreadContext.push("performWork()"); // <2>
+void performWork() {
+    ThreadContext.push("performWork()"); // <2>
+
+    LOGGER.debug("Performing work"); // <3>
+    // Perform the work
+
+    ThreadContext.pop(); // <4>
+}
 
-LOGGER.debug("Performing work"); // <3>
+ThreadContext.clear(); // <5>
 ----
-<1> Associating properties with the logging context map of the thread
-<2> Pushing properties to the logging context stack of the thread
+<1> Adding properties to the thread context map
+<2> Pushing properties to the thread context stack
 <3> Added properties can later on be used to, for instance, filter the log event, provide extra information in the layout, etc.
+<4> Popping the last pushed property from the thread context stack
+<5> Clearing the thread context (for both stack and map!)
 
 [CAUTION]
 ====

Diff for: src/site/antora/modules/ROOT/pages/manual/extending.adoc

@@ -580,32 +580,6 @@ ListAppender list1 = ListAppender.createAppender("List1", true, false, null, nul
 ListAppender list2 = ListAppender.newBuilder().setName("List1").setEntryPerNewLine(true).build();
 ----
 
-[#Custom_ContextDataProvider]
-== Custom ContextDataProvider
-
-The link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider.html[`ContextDataProvider`]
-(introduced in Log4j 2.13.2) is an interface applications and libraries can use to inject
-additional key-value pairs into the LogEvent's context data. Log4j
-uses `java.util.ServiceLoader` to locate and load `ContextDataProvider` instances.
-Log4j itself adds the ThreadContext data to the LogEvent using 
-`org.apache.logging.log4j.core.impl.ThreadContextDataProvider`. Custom implementations
-should implement the `org.apache.logging.log4j.core.util.ContextDataProvider` interface and
-declare it as a service by defining the implmentation class in a file named
-`META-INF/services/org.apache.logging.log4j.core.util.ContextDataProvider`.
-
-== Custom ThreadContextMap implementations
-
-A garbage-free `StringMap`-based context map can be installed by setting
-system property `log4j2.garbagefreeThreadContextMap` to true.
-
-Any custom link:../javadoc/log4j-core/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`]
-implementation can be installed by setting system property `log4j2.threadContextMap` 
-to the fully qualified class name of the class implementing the `ThreadContextMap` 
-interface. By also implementing the `ReadOnlyThreadContextMap` interface, your custom
-`ThreadContextMap` implementation will be accessible to applications via the
-link:../javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html#getThreadContextMap()[`ThreadContext::getThreadContextMap`]
-method.
-
 [#Custom_Plugins]
 == Custom Plugins
 

Diff for: src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc

@@ -209,7 +209,8 @@ The `Unbox.box(primitive)` methods write directly into a `StringBuilder`, and th
 Not all Log4j API feature set is garbage-free, specifically:
 
 * The `ThreadContext` map (aka. MDC) is not garbage-free by default, but can be configured to be garbage-free by setting xref:#log4j2.garbagefreeThreadContextMap[the `log4j2.garbagefreeThreadContextMap` system property] to `true`.
-* The `ThreadContext` stack is not garbage-free.
+* The `ThreadContext` stack (aka. NDC) is not garbage-free.
+* xref:manual/scoped-context.adoc[] is not garbage-free.
 * Logging very large messages (i.e., more than xref:#log4j2.maxReusableMsgSize[`log4j2.maxReusableMsgSize`] characters, which defaults to 518), when all loggers are xref:manual/async.adoc[asynchronous loggers], will cause the internal `StringBuilder` in the
 `RingBuffer` to be trimmed back to their configured maximum size.
 * Logging messages containing `$\{variable}` substitutions creates temporary objects.