You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by vy...@apache.org on 2024/05/24 11:35:09 UTC
(logging-log4j2) branch 2.x updated (1b2a3b8b03 -> fefd16b7e6)
This is an automated email from the ASF dual-hosted git repository.
vy pushed a change to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
from 1b2a3b8b03 Update `org.apache.commons:commons-compress` to version `1.26.2` (#2612)
new 0be1c1faa3 Rename `5min.adoc` to `getting-started.adoc`
new ba30b951c2 Mention Log4j Kotlin and Log4j Scala in `api.adoc`
new e42bc4d1bd Remove redundant navigation items
new 4426dd471e Remove `runtime-dependencies.adoc`
new fefd16b7e6 Rewrite `thread-context.adoc` et al. (#2535)
The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/site/antora/modules/ROOT/nav.adoc | 8 +-
.../ROOT/pages/{5min.adoc => getting-started.adoc} | 2 +-
src/site/antora/modules/ROOT/pages/index.adoc | 2 +-
src/site/antora/modules/ROOT/pages/manual/api.adoc | 38 ++-
.../modules/ROOT/pages/manual/extending.adoc | 26 --
.../modules/ROOT/pages/manual/garbagefree.adoc | 3 +-
.../modules/ROOT/pages/manual/thread-context.adoc | 271 +++++++--------------
.../modules/ROOT/pages/runtime-dependencies.adoc | 270 --------------------
.../properties-thread-context.adoc | 3 +
src/site/resources/.htaccess | 3 +
10 files changed, 127 insertions(+), 499 deletions(-)
rename src/site/antora/modules/ROOT/pages/{5min.adoc => getting-started.adoc} (99%)
delete mode 100644 src/site/antora/modules/ROOT/pages/runtime-dependencies.adoc
(logging-log4j2) 05/05: Rewrite `thread-context.adoc` et al. (#2535)
Posted by vy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit fefd16b7e6fccbab8b3b7b0f29675e0d6005989f
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Fri May 24 13:30:44 2024 +0200
Rewrite `thread-context.adoc` et al. (#2535)
---
src/site/antora/modules/ROOT/pages/manual/api.adoc | 30 ++-
.../modules/ROOT/pages/manual/extending.adoc | 26 --
.../modules/ROOT/pages/manual/garbagefree.adoc | 3 +-
.../modules/ROOT/pages/manual/thread-context.adoc | 271 +++++++--------------
.../properties-thread-context.adoc | 3 +
5 files changed, 114 insertions(+), 219 deletions(-)
diff --git a/src/site/antora/modules/ROOT/pages/manual/api.adoc b/src/site/antora/modules/ROOT/pages/manual/api.adoc
index 4b46a776ef..a5edfcd650 100644
--- a/src/site/antora/modules/ROOT/pages/manual/api.adoc
+++ b/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,8 +317,13 @@ 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]
----
@@ -326,13 +331,22 @@ 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 --git a/src/site/antora/modules/ROOT/pages/manual/extending.adoc b/src/site/antora/modules/ROOT/pages/manual/extending.adoc
index f44af434b6..432d6768c1 100644
--- a/src/site/antora/modules/ROOT/pages/manual/extending.adoc
+++ b/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 --git a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
index bcce913013..d06ea276c4 100644
--- a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
+++ b/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.
diff --git a/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc b/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc
index d8a1e1aa4d..5b4cf6cfb3 100644
--- a/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc
@@ -17,224 +17,127 @@
= Thread Context
-Log4j introduced the concept of the Mapped Diagnostic Context or MDC. It
-has been documented and discussed in numerous places including
-https://veerasundar.com/blog/log4j-mdc-mapped-diagnostic-context-what-and-why/[Log4j
-MDC: What and Why] and
-http://blog.f12.no/wp/2004/12/09/log4j-and-the-mapped-diagnostic-context/[Log4j
-and the Mapped Diagnostic Context]. In addition, Log4j 1.x provides
-support for a Nested Diagnostic Context or NDC. It too has been
-documented and discussed in various places such as
-http://lstierneyltd.com/blog/development/log4j-nested-diagnostic-contexts-ndc/[Log4j
-NDC]. SLF4J/Logback followed with its own implementation of the MDC,
-which is documented very well at
-http://logback.qos.ch/manual/mdc.html[Mapped Diagnostic Context].
-
-Log4j 2 continues with the idea of the MDC and the NDC but merges them
-into a single Thread Context. The Thread Context Map is the equivalent
-of the MDC and the Thread Context Stack is the equivalent of the NDC.
-Although these are frequently used for purposes other than diagnosing
-problems, they are still frequently referred to as the MDC and NDC in
-Log4j 2 since they are already well known by those acronyms.
-
-== Fish Tagging
-
-Most real-world systems have to deal with multiple clients
-simultaneously. In a typical multithreaded implementation of such a
-system, different threads will handle different clients. Logging is
-especially well suited to trace and debug complex distributed
-applications. A common approach to differentiate the logging output of
-one client from another is to instantiate a new separate logger for each
-client. This promotes the proliferation of loggers and increases the
-management overhead of logging.
-
-A lighter technique is to uniquely stamp each log request initiated from
-the same client interaction. Neil Harrison described this method in the
-book "Patterns for Logging Diagnostic Messages," in _Pattern Languages
-of Program Design 3_, edited by R. Martin, D. Riehle, and F. Buschmann
-(Addison-Wesley, 1997). Just as a fish can be tagged and have its
-movement tracked, 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. We call this _Fish Tagging_.
-
-Log4j provides two mechanisms for performing Fish Tagging; the Thread
-Context Map and the Thread Context Stack. The Thread Context Map allows
-any number of items to be added and be identified using key/value pairs.
-The Thread Context Stack allows one or more items to be pushed on the
-Stack and then be identified by their order in the Stack or by the data
-itself. Since key/value pairs are more flexible, the Thread Context Map
-is recommended when data items may be added during the processing of the
-request or when there are more than one or two items.
-
-To uniquely stamp each request using the Thread Context Stack, the user
-pushes contextual information on to the Stack.
-
-[#nested-diagnostic-context]
-[source,java]
-----
-ThreadContext.push(UUID.randomUUID().toString()); // Add the fishtag;
+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 is one of many xref:manual/api.adoc#fish-tagging[_fish tagging_ capabilities provided by Log4j API].
-logger.debug("Message 1");
+[#usage]
+== Usage
-// ...
+The entry point for associating logging-related information with the executing thread is link:../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html[`ThreadContext`].
+It offers both
-logger.debug("Message 2");.
+* 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:
-ThreadContext.pop();
+[source,java]
----
+ThreadContext.put("ipAddress", request.getRemoteAddr()); // <1>
+ThreadContext.put("hostName", request.getServerName()); // <1>
+ThreadContext.put("loginId", session.getAttribute("loginId")); // <1>
-The alternative to the Thread Context Stack is the Thread Context Map.
-In this case, attributes associated with the request being processed are
-adding at the beginning and removed at the end as follows:
+void performWork() {
+ ThreadContext.push("performWork()"); // <2>
-[#mapped-diagnostic-context]
-[source,java]
+ LOGGER.debug("Performing work"); // <3>
+ // Perform the work
+
+ ThreadContext.pop(); // <4>
+}
+
+ThreadContext.clear(); // <5>
----
-ThreadContext.put("id", UUID.randomUUID().toString()); // Add the fishtag;
-ThreadContext.put("ipAddress", request.getRemoteAddr());
-ThreadContext.put("loginId", session.getAttribute("loginId"));
-ThreadContext.put("hostName", request.getServerName());
+<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!)
-// ...
+[#CloseableThreadContext]
+=== Auto-clearing thread context
-logger.debug("Message 1");
+When placing items on the thread context stack or map, it's necessary to remove them again when appropriate.
+To assist with this, you can use link:../log4j-api/apidocs/org/apache/logging/log4j/CloseableThreadContext.html[`CloseableThreadContext`] (implementing http://docs.oracle.com/javase/7/docs/api/java/lang/AutoCloseable.html[`AutoCloseable`]) in a try-with-resources block:
-// ...
+[source,java]
+----
+try (CloseableThreadContext.Instance ignored = CloseableThreadContext
+ .put("ipAddress", request.getRemoteAddr()) // <1>
+ .push("performWork()")) { // <1>
-logger.debug("Message 2");
+ LOGGER.debug("Performing work"); // <2>
+ // Perform the work
-// ...
+}
-ThreadContext.clear();
+// ... // <3>
----
+<1> Making thread context changes that will only be visible **within the scope of the try-with-resources block**
+<2> Added properties can later on be used to, for instance, filter the log event, provide extra information in the layout, etc.
+<3> Outside the scope of the try-with-resources block made thread context changes will not be visible
-== CloseableThreadContext
+[#init]
+=== Initializing thread context
-When placing items on the stack or map, it's necessary to remove then
-again when appropriate. To assist with this, the
-`CloseableThreadContext` implements the
-http://docs.oracle.com/javase/7/docs/api/java/lang/AutoCloseable.html[`AutoCloseable`
-interface]. This allows items to be pushed to the stack or put in the
-map, and removed when the `close()` method is called - or automatically
-as part of a try-with-resources. For example, to temporarily push
-something on to the stack and then remove it:
+It is a common use case that a single threaded execution fans out to multiple threads by means of a thread pool.
+In such a case, you need to clone the context of the current thread to the ones in the pool.
+For that purpose, you can use `putAll()` and `pushAll()` methods that are provided by both `ThreadContext` and `CloseableThreadContext`:
[source,java]
----
-// Add to the ThreadContext stack for this try block only;
-try (final CloseableThreadContext.Instance ctc = CloseableThreadContext.push(UUID.randomUUID().toString())) {
-
- logger.debug("Message 1");
+LOGGER.debug("Starting background thread for user");
-// ...
+Map<String, String> mdc = ThreadContext.getImmutableContext(); // <1>
+List<String> ndc = ThreadContext.getImmutableStack().asList(); // <1>
- logger.debug("Message 2");
+executor.submit(() -> {
+ try (CloseableThreadContext.Instance ignored = CloseableThreadContext
+ .putAll(values) // <2>
+ .pushAll(messages)) { // <2>
-// ...
+ LOGGER.debug("Processing for user started");
+ // ...
-}
+ }
+});
----
+<1> Taking a snapshot of the thread context
+<2> Initializing the thread context for the background task
-Or, to temporarily put something in the map:
-
-[source,java]
-----
-// Add to the ThreadContext map for this try block only;
-try (final CloseableThreadContext.Instance ctc = CloseableThreadContext.put("id", UUID.randomUUID().toString())
- .put("loginId", session.getAttribute("loginId"))) {
+[#config]
+== Configuration
- logger.debug("Message 1");
+You can configure thread context using following properties:
-// ...
+include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+1]
- logger.debug("Message 2");
+[#extending]
+== Extending
-// ...
+Certain thread context implementation details can be customized to fit your use case.
-}
-----
+[#custom-ContextDataProvider]
+=== Custom thread context data provider
-If you're using a thread pool, then you can initialise a
-CloseableThreadContext by using the
-`putAll(final Map<String, String> values)` and/or
-`pushAll(List<String> messages)` methods;
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider.html[`ContextDataProvider`] is an interface applications and libraries can use to inject additional properties into a log events' context data.
+Log4j uses `java.util.ServiceLoader` to locate and load `ContextDataProvider` instances.
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/ThreadContextDataProvider.html[`ThreadContextDataProvider`] is the default implementation provided.
+You can provide a custom `ContextDataProvider` implementation as follows:
-[source,java]
+. Create the following file in your class path:
++
+[source,text]
----
-for( final Session session : sessions ) {
- try (final CloseableThreadContext.Instance ctc = CloseableThreadContext.put("loginId", session.getAttribute("loginId"))) {
- logger.debug("Starting background thread for user");
- final Map<String, String> values = ThreadContext.getImmutableContext();
- final List<String> messages = ThreadContext.getImmutableStack().asList();
- executor.submit(new Runnable() {
- public void run() {
- try (final CloseableThreadContext.Instance ctc = CloseableThreadContext.putAll(values).pushAll(messages)) {
- logger.debug("Processing for user started");
-
-// ...
-
- logger.debug("Processing for user completed");
- }
- });
- }
-}
+META-INF/services/org.apache.logging.log4j.core.util.ContextDataProvider
----
+. Write the fully-qualified class name of your custom implementation (e.g., `com.mycompany.CustomContextDataProvider`) to the file created in the previous step
+
+[#custom-ThreadContextMap]
+=== Custom thread context map
+
+Custom thread context map implementations can be provided by setting xref:#log4j2.threadContextMap[the `log4j2.threadContextMap` system property] to the fully-qualified class name of the custom implementation class extending from link:../javadoc/log4j-core/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`].
-== Implementation details
-
-The Stack and the Map are managed per thread and are based on
-http://docs.oracle.com/javase/6/docs/api/java/lang/ThreadLocal.html[`ThreadLocal`]
-by default. The Map can be configured to use an
-http://docs.oracle.com/javase/6/docs/api/java/lang/InheritableThreadLocal.html[`InheritableThreadLocal`]
-(see the Configuration section). When configured this way, the contents of the Map will be passed
-to child threads. However, as discussed in the
-http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/Executors.html#privilegedThreadFactory()[`Executors`]
-class and in other cases where thread pooling is utilized, the
-ThreadContext may not always be automatically passed to worker threads.
-In those cases the pooling mechanism should provide a means for doing
-so. The `getContext()` and `cloneStack()` methods can be used to obtain
-copies of the Map and Stack respectively.
-
-Note that all methods of the
-link:../javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html[`ThreadContext`]
-class are static.
-
-=== Configuration
-
-* Set the system property `log4j2.disableThreadContextMap` to `true` to disable the Thread Context Map.
-* Set the system property `log4j2.disableThreadContextStack` to `true` to disable the Thread Context Stack.
-* Set the system property `log4j2.disableThreadContext` to `true` to disable both the Thread Context Map and Stack.
-* Set the system property `log4j2.isThreadContextMapInheritable` to `true` to enable child threads to inherit the Thread
-Context Map.
-
-== Including the ThreadContext when writing logs
-
-The
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternLayout.html[`PatternLayout`]
-provides mechanisms to print the contents of the
-link:../javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html[`ThreadContext`]
-Map and Stack.
-
-* Use `%X` by itself to include the full contents of the Map.
-* Use `%X\{key}` to include the specified key.
-* Use `%x` to include the full contents of the
-http://docs.oracle.com/javase/6/docs/api/java/util/Stack.html[Stack].
-
-== Custom context data injectors for non thread-local context data
-
-With the ThreadContext logging statements can be tagged so log entries
-that were related in some way can be linked via these tags. The
-limitation is that this only works for logging done on the same
-application thread (or child threads when configured).
-
-Some applications have a thread model that delegates work to other
-threads, and in such models, tagging attributes that are put into a
-thread-local map in one thread are not visible in the other threads and
-logging done in the other threads will not show these attributes.
-
-Log4j 2.7 adds a flexible mechanism to tag logging statements with
-context data coming from other sources than the ThreadContext. See the
-manual page on xref:manual/extending.adoc#Custom_ContextDataProvider[extending
-Log4j] for details.
+While providing a custom thread context map implementation, you are advised to also extend from link:../javadoc/log4j-core/org/apache/logging/log4j/spi/ReadOnlyThreadContextMap.html[`ReadOnlyThreadContextMap`] too.
+By this way, your custom thread context map implementation will be accessible to applications via
+link:../javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html#getThreadContextMap()[`ThreadContext.getThreadContextMap()`].
diff --git a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context.adoc b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context.adoc
index a3936eb2e4..71ff2533a4 100644
--- a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context.adoc
+++ b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context.adoc
@@ -85,6 +85,9 @@ GarbageFree:: a garbage-free implementation.
If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+Note that, as explained in
+http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/Executors.html#privilegedThreadFactory()[Java's `Executors#privilegedThreadFactory()`], when you are dealing with _privileged threads_, thread context might not get propagated completely.
+
// tag::gcfree[]
[id=log4j2.garbagefreeThreadContextMap]
(logging-log4j2) 01/05: Rename `5min.adoc` to `getting-started.adoc`
Posted by vy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 0be1c1faa3e95fe5a4749428ee0848d451800624
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Fri May 24 10:21:35 2024 +0200
Rename `5min.adoc` to `getting-started.adoc`
---
src/site/antora/modules/ROOT/nav.adoc | 2 +-
src/site/antora/modules/ROOT/pages/{5min.adoc => getting-started.adoc} | 2 +-
src/site/antora/modules/ROOT/pages/index.adoc | 2 +-
src/site/antora/modules/ROOT/pages/manual/api.adoc | 2 +-
4 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
index e82c69c6c7..fa0e44e630 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -24,7 +24,7 @@
.Resources
* xref:faq.adoc[F.A.Q.]
-* xref:5min.adoc[]
+* xref:getting-started.adoc[]
* xref:manual/migration.adoc[]
* xref:manual/cloud.adoc[]
* xref:development.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/5min.adoc b/src/site/antora/modules/ROOT/pages/getting-started.adoc
similarity index 99%
rename from src/site/antora/modules/ROOT/pages/5min.adoc
rename to src/site/antora/modules/ROOT/pages/getting-started.adoc
index 9271a8c43e..7c414463f6 100644
--- a/src/site/antora/modules/ROOT/pages/5min.adoc
+++ b/src/site/antora/modules/ROOT/pages/getting-started.adoc
@@ -15,7 +15,7 @@
limitations under the License.
////
-= Log4j explained in 5 minutes
+= Getting started
This document aims to guide you through the most important aspects of logging with Log4j.
It is not a comprehensive guide, but it should give you a good starting point.
diff --git a/src/site/antora/modules/ROOT/pages/index.adoc b/src/site/antora/modules/ROOT/pages/index.adoc
index a1d72e3718..128c273469 100644
--- a/src/site/antora/modules/ROOT/pages/index.adoc
+++ b/src/site/antora/modules/ROOT/pages/index.adoc
@@ -23,7 +23,7 @@ The project is actively maintained by a {logging-services-url}/team-list.html[te
[#shortcuts]
== Shortcuts
-- xref:5min.adoc[]
+- xref:getting-started.adoc[]
- xref:manual/installation.adoc[How can I install Log4j? Which dependencies are needed?]
- xref:manual/configuration.adoc[How can I configure my `log4j2.xml`?]
- xref:release-notes.adoc[Where are the release notes?]
diff --git a/src/site/antora/modules/ROOT/pages/manual/api.adoc b/src/site/antora/modules/ROOT/pages/manual/api.adoc
index cec0fc80a6..1d62b043e3 100644
--- a/src/site/antora/modules/ROOT/pages/manual/api.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/api.adoc
@@ -42,7 +42,7 @@ Log4j Core, {jul-link}, {logback-link} are the most well-known logging implement
[TIP]
====
Are you looking for a crash course on how to use Log4j in your application or library?
-See xref:5min.adoc[].
+See xref:getting-started.adoc[].
You can also check out xref:manual/installation.adoc[] for the complete installation instructions.
====
(logging-log4j2) 03/05: Remove redundant navigation items
Posted by vy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit e42bc4d1bd33988200ff6b9bfe6d292c009620b4
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Fri May 24 10:24:27 2024 +0200
Remove redundant navigation items
---
src/site/antora/modules/ROOT/nav.adoc | 6 ------
1 file changed, 6 deletions(-)
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
index fa0e44e630..65d5a8bb34 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -64,12 +64,6 @@
* xref:javadoc.adoc[Java API reference]
.Components
-* xref:log4j-api.adoc[]
-* xref:log4j-1.2-api.adoc[]
-* xref:log4j-slf4j-impl.adoc[]
-* xref:log4j-jul.adoc[]
-* xref:log4j-jpl.adoc[]
-* xref:log4j-to-slf4j.adoc[]
* xref:log4j-flume-ng.adoc[]
* xref:log4j-mongodb3.adoc[]
* xref:log4j-mongodb4.adoc[]
(logging-log4j2) 04/05: Remove `runtime-dependencies.adoc`
Posted by vy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 4426dd471eb5dcf2e109e87806205537794466e4
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Fri May 24 10:28:17 2024 +0200
Remove `runtime-dependencies.adoc`
Its content is outdated, and covered in `installation.adoc` and elsewhere in the site.
---
.../modules/ROOT/pages/runtime-dependencies.adoc | 270 ---------------------
src/site/resources/.htaccess | 3 +
2 files changed, 3 insertions(+), 270 deletions(-)
diff --git a/src/site/antora/modules/ROOT/pages/runtime-dependencies.adoc b/src/site/antora/modules/ROOT/pages/runtime-dependencies.adoc
deleted file mode 100644
index 5009374a06..0000000000
--- a/src/site/antora/modules/ROOT/pages/runtime-dependencies.adoc
+++ /dev/null
@@ -1,270 +0,0 @@
-////
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-////
-= Runtime Dependencies
-
-Some Log4J features depend on external libraries. This page lists the required and optional dependencies.
-
-As of version 2.10.0, the Log4j API is a named Java module (with a `module-info.java`). Since version 2.21.0, all the remaining artifacts are named modules. The characteristics of the modules are:
-
-[options="header"]
-|===
-| Artifact Name | Module Name | Module Characteristics
-
-| log4j-api
-| org.apache.logging.log4j
-| Module Directive Notes
-exports org.apache.logging.log4j
-exports org.apache.logging.log4j.message
-exports org.apache.logging.log4j.simple
-exports org.apache.logging.log4j.spi
-exports org.apache.logging.log4j.spi
-exports org.apache.logging.log4j.util Some classes in this package are used by the logging implementation and should be considered private. The module info definition may be modified in the future to export these only to the logging implementation.
-uses org.apache.logging.log4j.spi.Provider Service that must be provided by the logging implementation.
-
-
-| log4j-appserver
-| org.apache.logging.log4j.appserver
-| Named Module
-
-| log4j-cassandra
-| org.apache.logging.log4j.cassandra
-| Named Module
-
-| log4j-core
-| org.apache.logging.log4j.core
-| Named Module. Most of its dependencies are optional.
-
-| log4j-couchdb
-| org.apache.logging.log4j.couchdb
-| Named Module
-
-| log4j-docker
-| org.apache.logging.log4j.docker
-| Named Module
-
-| log4j-1.2-api
-| org.apache.log4j
-| Named Module
-
-| log4j-flume-ng
-| org.apache.logging.log4j.flume
-| Named Module
-
-| log4j-iostreams
-| org.apache.logging.log4j.iostreams
-| Named Module
-
-| log4j-jakarta-smtp
-| org.apache.logging.log4j.smtp
-| Named Module
-
-| log4j-jakarta-web
-| org.apache.logging.log4j.web
-| Named Module. Uses the same name as `log4j-web` since it is its Jakarta EE 9 equivalent.
-
-| log4j-jcl
-| org.apache.logging.log4j.jcl
-| Named Module
-
-| log4j-jul
-| org.apache.logging.log4j.jul
-| Named Module
-
-| log4j-mongodb
-| org.apache.logging.log4j.mongodb
-| Named Module
-
-| log4j-slf4j-impl
-| org.apache.logging.log4j.slf4j.impl
-| Named Module
-
-| log4j-slf4j2-impl
-| org.apache.logging.log4j.slf4j2.impl
-| Named Module
-
-| log4j-taglib
-| org.apache.logging.log4j.taglib
-| Named Module
-
-| log4j-to-slf4j
-| org.apache.logging.log4j.to.slf4j
-| Named Module
-
-| log4j-web
-| org.apache.logging.log4j.web
-| Named Module. Uses the same name as `log4j-jakarta-web` since it is its Java EE 8 equivalent.
-|===
-
-As of version 2.9.1, Log4j supports Java 9 but will still work in Java 7 or 8. In this version, log4j-api is packaged as a multi-release jar and supports the use of the StackWalker and Process APIs.
-
-As of version 2.4, Log4J requires Java 7.
-
-Log4j version 2.3 and older require Java 6.
-
-== log4j-api
-
-The Log4J xref:log4j-api.adoc[API] module has no external dependencies.
-
-== log4j-core
-
-The Log4J implementation has several optional dependencies.
-
-Optional Dependencies per Feature in Log4J Implementation:
-
-[options="header"]
-|===
-| Feature | Requirements
-
-| XML configuration
-| -
-
-| Properties configuration
-| -
-
-| JSON configuration
-| https://github.com/FasterXML/jackson[Jackson core and databind]
-
-| YAML configuration
-| https://github.com/FasterXML/jackson[Jackson databind] and https://github.com/FasterXML/jackson-dataformat-yaml[YAML data format]
-
-| CSV Layout
-| https://commons.apache.org/proper/commons-csv/[Apache Commons CSV]
-
-| JSON Layout
-| https://github.com/FasterXML/jackson[Jackson core and databind]
-
-| XML Layout
-| https://github.com/FasterXML/jackson[Jackson core, databind and dataformat XML] and `com.fasterxml.woodstox:woodstox-core:5.0.2`
-
-| YAML Layout
-| https://github.com/FasterXML/jackson[Jackson core, databind] and https://github.com/FasterXML/jackson-dataformat-yaml[YAML data format]
-
-| Async Loggers
-| https://lmax-exchange.github.io/disruptor/[LMAX Disruptor]
-
-| Kafka Appender
-| https://kafka.apache.org/[Kafka client library]. Note that you need to use a version of the Kafka client library matching the Kafka server used.
-
-| SMTP Appender
-| an implementation of `javax.mail`
-
-| JMS Appender
-| a JMS broker like https://activemq.apache.org/[Apache ActiveMQ]
-
-| Windows console color support
-| https://fusesource.github.io/jansi/[Jansi]
-
-| JDBC Appender
-| a JDBC driver for the database you choose to write events to
-
-| JPA Appender
-| the Java Persistence API classes, a JPA provider implementation, and a decorated entity that the user implements. It also requires an appropriate JDBC driver
-
-| NoSQL Appender with MongoDB provider
-| MongoDB Java Client driver and Log4j MongoDB library
-
-| NoSQL Appender with Apache CouchDB provider
-| LightCouch CouchDB client library and Log4j CouchDB library
-
-| Cassandra Appender
-| Datastax Cassandra driver and Log4j Cassandra library
-
-| Bzip2, Deflate, Pack200, and XZ compression on rollover
-| https://commons.apache.org/proper/commons-compress/[Apache Commons Compress]. In addition, XZ requires https://tukaani.org/xz/java.html[xz-java] and ZStandard requires https://github.com/luben/zstd-jni[zstd-jni]
-
-| ZeroMQ Appender
-| The ZeroMQ appender uses the https://github.com/zeromq/jeromq[JeroMQ] library which is licensed under the terms of the Mozilla Public License Version 2.0 (MPLv2). For details see the file https://github.com/zeromq/jeromq/blob/master/LICENSE[LICENSE] included with the JeroMQ distribution.
-|===
-
-== log4j-docker
-
-xref:log4j-docker.adoc[Log4j Docker Support] requires https://github.com/FasterXML/jackson[Jackson annotations, core, and databind].
-
-== log4j-jcl
-
-The xref:log4j-jcl.adoc[Commons Logging Bridge] requires https://commons.apache.org/proper/commons-logging/[Commons Logging].
-
-== log4j-1.2-api
-
-The xref:log4j-1.2-api.adoc[Log4j 1.2 Bridge] has no external dependencies. This only requires the Log4j API. Including Log4j Core provides optional, extra functionality.
-
-== log4j-slf4j-impl
-
-The Log4j 2 xref:log4j-slf4j-impl.adoc[SLF4J Binding] depends on the https://www.slf4j.org/[SLF4J] API.
-
-[WARNING]
-.Do not use this with the log4j-to-slf4j module.
-====
-
-== log4j-jul
-
-The Log4j 2 xref:log4j-jul.adoc[Java Util Logging Adapter] has no external dependencies. It optionally depends on the xref:log4j-api.adoc[Log4j Core] library. The only required module is the Log4j API.
-
-== log4j-to-slf4j
-
-The xref:log4j-to-slf4j.adoc[Log4j 2 to SLF4J Adapter] requires the https://www.slf4j.org/[SLF4J] API and an SLF4J implementation.
-
-[WARNING]
-.Do not use this with the log4j-slf4j-impl module.
-====
-
-== log4j-flume-ng
-
-The xref:log4j-flume-ng.adoc[Flume Appender] requires https://flume.apache.org/[Apache Flume] and https://avro.apache.org/[Apache Avro]. The persistent agent uses Berkeley DB.
-
-== log4j-spring-cloud-config-client
-
-xref:log4j-spring-cloud-config-client.adoc[Log4j Spring Cloud Config Client] requires https://spring.io/projects/spring-cloud-config[Spring Cloud Config]. https://spring.io/projects/spring-cloud-bus[Spring Cloud Bus] is required if notification of logging configuration changes is desired. https://spring.io/projects/spring-boot[Spring Boot] is required but applications do not have to be packaged as a Spring Boot application.
-
-== log4j-taglib
-
-The Log4j xref:log4j-taglib.adoc[Log Tag Library] requires the https://jakarta.apache.org/taglibs/log/[Jakarta Commons Log Taglib] and the Servlet API.
-
-== log4j-web
-
-The Log4j xref:log4j-web.adoc[Web] module requires the Servlet API. Note that this works with the Servlet 2.5 API as well as the Servlet 3.x API.
-
-== log4j-couchdb
-
-The Log4J xref:log4j-couchdb.adoc[CouchDB] module depends on the https://www.lightcouch.org/[LightCouch] CouchDB client library.
-
-== log4j-mongodb3
-
-The Log4J xref:log4j-mongodb3.adoc[MongoDB 3] module depends on the https://docs.mongodb.org/ecosystem/drivers/java/[MongoDB Java Client driver].
-
-== log4j-mongodb4
-
-The Log4J xref:log4j-mongodb4.adoc[MongoDB 4] module depends on the https://docs.mongodb.org/ecosystem/drivers/java/[MongoDB Java Client driver].
-
-== log4j-cassandra
-
-The Log4J xref:log4j-cassandra.adoc[Cassandra] module depends on the https://docs.datastax.com/en/developer/driver-matrix/doc/javaDrivers.html[Datastax Cassandra driver].
-
-== log4j-iostreams
-
-The Log4j xref:log4j-iostreams.adoc[IO Streams] module has no external dependencies. This only requires the Log4j API.
-
-== log4j-jakarta-smtp
-
-The Log4j Simple Mail Transfer Protocol (SMTP) Appender, version for Jakarta EE 9 module has 2 external runtime dependencies for the jakarta.activation-api and jakarta.mail-api.
-
-. org.eclipse.angus:angus-activation
-. org.eclipse.angus:jakarta.mail
-
-== log4j-jakarta-web
-
-The Log4j xref:log4j-jakarta-web.adoc[Jakarta-Web] module for Jakarta EE 9+ web servlet containers requires the Servlet API and `log4j-core`.
diff --git a/src/site/resources/.htaccess b/src/site/resources/.htaccess
index 9072d12ac5..9053f5bd22 100644
--- a/src/site/resources/.htaccess
+++ b/src/site/resources/.htaccess
@@ -32,3 +32,6 @@ RewriteRule "^manual/usage(\.html)?$" "%1/manual/api.html" [R=permanent]
RewriteCond "%{REQUEST_URI}" "^(/log4j/[23]\.x)/"
RewriteRule "^release-notes/(index(\.html)?)?$" "%1/release-notes.html" [R=permanent]
+
+RewriteCond "%{REQUEST_URI}" "^(/log4j/[23]\.x)/"
+RewriteRule "^runtime-dependencies\.html" "%1/manual/installation.html" [R=permanent]
(logging-log4j2) 02/05: Mention Log4j Kotlin and Log4j Scala in `api.adoc`
Posted by vy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit ba30b951c25b066645abb7edfede3f07d33a1cf2
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Fri May 24 10:23:52 2024 +0200
Mention Log4j Kotlin and Log4j Scala in `api.adoc`
---
src/site/antora/modules/ROOT/pages/manual/api.adoc | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/src/site/antora/modules/ROOT/pages/manual/api.adoc b/src/site/antora/modules/ROOT/pages/manual/api.adoc
index 1d62b043e3..4b46a776ef 100644
--- a/src/site/antora/modules/ROOT/pages/manual/api.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/api.adoc
@@ -53,6 +53,12 @@ Log4j API provides
This page tries to cover the most prominent Log4j API features that libraries and applications can code to.
+[TIP]
+====
+Did you know that Log4j provides specialized APIs for Kotlin and Scala?
+Check out {logging-services-url}/log4j/kotlin[Log4j Kotlin] and {logging-services-url}/log4j/scala[Log4j Scala] projects for details.
+====
+
== Introduction
include::partial$manual/api-intro.adoc[leveloffset=+1]