This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch feature/move-thread-context in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 570a1fadd37e2263c92c2024dd23f2cd355ddbbf Author: Piotr P. Karwasz <[email protected]> AuthorDate: Mon Jun 24 16:34:01 2024 +0200 Update documentation --- .../modules/ROOT/pages/manual/garbagefree.adoc | 2 +- .../modules/ROOT/pages/manual/simple-logger.adoc | 12 ++++++--- .../ROOT/pages/manual/systemproperties.adoc | 2 +- .../modules/ROOT/pages/manual/thread-context.adoc | 23 ++++++++++++++--- ...xt.adoc => properties-thread-context-core.adoc} | 4 +-- ...> properties-thread-context-simple-logger.adoc} | 29 ++-------------------- 6 files changed, 33 insertions(+), 39 deletions(-) diff --git a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc index 5bc6438cfa..33400a31ea 100644 --- a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc @@ -69,7 +69,7 @@ include::partial$manual/systemproperties/properties-meta.adoc[leveloffset=+2] include::partial$manual/systemproperties/properties-garbage-collection.adoc[leveloffset=+2] -include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+2,tag=gcfree] +include::partial$manual/systemproperties/properties-thread-context-core.adoc[leveloffset=+2,tag=gcfree] [#Layouts] === Layouts diff --git a/src/site/antora/modules/ROOT/pages/manual/simple-logger.adoc b/src/site/antora/modules/ROOT/pages/manual/simple-logger.adoc index e9f8f7370f..15325abbb2 100644 --- a/src/site/antora/modules/ROOT/pages/manual/simple-logger.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/simple-logger.adoc @@ -24,11 +24,17 @@ This is a convenience for environments where either a fully-fledged logging impl [#config] == Configuration +[#logger] +=== Logger + `SimpleLogger` can be configured using the following system properties: -include::partial$manual/systemproperties/properties-simple-logger.adoc[leveloffset=+1] +include::partial$manual/systemproperties/properties-simple-logger.adoc[leveloffset=+2] +[#thread-context] === Thread context -Simple Logger supports the same properties as Log4j Core for the configuration of the thread context. -See xref:manual/systemproperties.adoc#properties-thread-context[] for details. +For the configuration of the thread context, +Simple Logger supports a subset of the properties supported by Log4j Core: + +include::partial$manual/systemproperties/properties-thread-context-simple-logger.adoc[leveloffset=+2] \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc b/src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc index 3c1618673c..05463eef8b 100644 --- a/src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc @@ -184,7 +184,7 @@ The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to {slf4j-ur The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls. ==== -include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+2] +include::partial$manual/systemproperties/properties-thread-context-core.adoc[leveloffset=+2] [id=properties-transport-security] === Transport security 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 771394cbfa..8b61cc9474 100644 --- a/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc @@ -63,8 +63,7 @@ When placing items on the thread context stack or map, it's necessary to remove To assist with this, you can use link:../javadoc/log4j-api/org/apache/logging/log4j/CloseableThreadContext.html[`CloseableThreadContext`] (implementing -http://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/AutoCloseable.html[`AutoCloseable`]) -in a try-with-resources block: +http://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/AutoCloseable.html[`AutoCloseable`]) in a try-with-resources block: [source,java] ---- @@ -116,9 +115,25 @@ executor.submit(() -> { [#config] == Configuration -You can configure thread context using following properties: +Since the thread context is inherently linked to the logging implementation, its configuration options depend on the logging implementation used: -include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+1] +Simple Logger:: ++ +See xref:manual/simple-logger.adoc#thread-context[Thread context configuration of Simple Logger]. + +Log4j Core:: ++ +See xref:manual/systemproperties.adoc#properties-thread-context[Thread context configuration of Log4j Core]. + +SLF4J implementations (Logback):: ++ +All `ThreadContext` method calls are translated into equivalent +https://www.slf4j.org/api/org/slf4j/MDC.html[`org.slf4j.MDC`] +method calls. + +JUL:: ++ +All `ThreadContext` method calls are a no-op. [#extending] == Extending 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-core.adoc similarity index 95% copy from src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context.adoc copy to src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context-core.adoc index 684974cb8d..93be8c4a59 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-core.adoc @@ -67,16 +67,14 @@ or predefined constant | Default value | `WebApp` -(GC-free mode: `CopyOnWrite`) |=== Fully specified class name of a custom link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`] -implementation class or one of the predefined constants: +implementation class or (since version 2.24.0) one of the predefined constants: NoOp:: to disable the thread context, WebApp:: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks, -CopyOnWrite:: a copy-on-write implementation, GarbageFree:: a garbage-free implementation. // end::gcfree[] 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-simple-logger.adoc similarity index 78% rename from src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context.adoc rename to src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context-simple-logger.adoc index 684974cb8d..35a9060b47 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-simple-logger.adoc @@ -50,8 +50,6 @@ If `true`, the `ThreadContext` stack is disabled. If `true`, the `ThreadContext` map is disabled. -// tag::gcfree[] - [id=log4j2.threadContextMap] == `log4j2.threadContextMap` @@ -62,24 +60,15 @@ If `true`, the `ThreadContext` map is disabled. | Type | link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`Class<? extends ThreadContextMap>`] -or predefined constant | Default value -| `WebApp` +| link:../javadoc/log4j-api/org/apache/logging/log4j/spi/DefaultThreadContextMap.html[`DefaultThreadContextMap`] -(GC-free mode: `CopyOnWrite`) |=== Fully specified class name of a custom link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`] -implementation class or one of the predefined constants: - -NoOp:: to disable the thread context, -WebApp:: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks, -CopyOnWrite:: a copy-on-write implementation, -GarbageFree:: a garbage-free implementation. - -// end::gcfree[] +implementation class. [id=isThreadContextMapInheritable] == `log4j2.isThreadContextMapInheritable` @@ -96,17 +85,3 @@ If `true` uses an `InheritableThreadLocal` to copy the thread context map to new Note that, as explained in https://docs.oracle.com/javase/{java-target-version}/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] -== `log4j2.garbagefreeThreadContextMap` - -[cols="1h,5"] -|=== -| Env. variable | `LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP` -| Default value | `false` -|=== - -If set to `true` selects a garbage-free thread context map implementation. - -// end::gcfree[]
