Skip to content

Commit 570a1fa

Browse files
ppkarwaszppkarwasz
committed
Update documentation
1 parent 65abe46 commit 570a1fa

File tree

6 files changed

+118
-12
lines changed

6 files changed

+118
-12
lines changed

‎src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ include::partial$manual/systemproperties/properties-meta.adoc[leveloffset=+2]
6969
7070
include::partial$manual/systemproperties/properties-garbage-collection.adoc[leveloffset=+2]
7171
72-
include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+2,tag=gcfree]
72+
include::partial$manual/systemproperties/properties-thread-context-core.adoc[leveloffset=+2,tag=gcfree]
7373
7474
[#Layouts]
7575
=== Layouts

‎src/site/antora/modules/ROOT/pages/manual/simple-logger.adoc‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,17 @@ This is a convenience for environments where either a fully-fledged logging impl
2424
[#config]
2525
== Configuration
2626
27+
[#logger]
28+
=== Logger
29+
2730
`SimpleLogger` can be configured using the following system properties:
2831
29-
include::partial$manual/systemproperties/properties-simple-logger.adoc[leveloffset=+1]
32+
include::partial$manual/systemproperties/properties-simple-logger.adoc[leveloffset=+2]
3033
34+
[#thread-context]
3135
=== Thread context
3236
33-
Simple Logger supports the same properties as Log4j Core for the configuration of the thread context.
34-
See xref:manual/systemproperties.adoc#properties-thread-context[] for details.
37+
For the configuration of the thread context,
38+
Simple Logger supports a subset of the properties supported by Log4j Core:
39+
40+
include::partial$manual/systemproperties/properties-thread-context-simple-logger.adoc[leveloffset=+2]

‎src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,7 @@ The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to {slf4j-ur
184184
The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
185185
====
186186
187-
include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+2]
187+
include::partial$manual/systemproperties/properties-thread-context-core.adoc[leveloffset=+2]
188188
189189
[id=properties-transport-security]
190190
=== Transport security

‎src/site/antora/modules/ROOT/pages/manual/thread-context.adoc‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,7 @@ When placing items on the thread context stack or map, it's necessary to remove
6363
To assist with this, you can use
6464
link:../javadoc/log4j-api/org/apache/logging/log4j/CloseableThreadContext.html[`CloseableThreadContext`]
6565
(implementing
66-
http://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/AutoCloseable.html[`AutoCloseable`])
67-
in a try-with-resources block:
66+
http://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/AutoCloseable.html[`AutoCloseable`]) in a try-with-resources block:
6867
6968
[source,java]
7069
----
@@ -116,9 +115,25 @@ executor.submit(() -> {
116115
[#config]
117116
== Configuration
118117
119-
You can configure thread context using following properties:
118+
Since the thread context is inherently linked to the logging implementation, its configuration options depend on the logging implementation used:
120119
121-
include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+1]
120+
Simple Logger::
121+
+
122+
See xref:manual/simple-logger.adoc#thread-context[Thread context configuration of Simple Logger].
123+
124+
Log4j Core::
125+
+
126+
See xref:manual/systemproperties.adoc#properties-thread-context[Thread context configuration of Log4j Core].
127+
128+
SLF4J implementations (Logback)::
129+
+
130+
All `ThreadContext` method calls are translated into equivalent
131+
https://www.slf4j.org/api/org/slf4j/MDC.html[`org.slf4j.MDC`]
132+
method calls.
133+
134+
JUL::
135+
+
136+
All `ThreadContext` method calls are a no-op.
122137
123138
[#extending]
124139
== Extending

‎src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context.adoc‎ renamed to ‎src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context-core.adoc‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,16 +67,14 @@ or predefined constant
6767
| Default value
6868
| `WebApp`
6969
70-
(GC-free mode: `CopyOnWrite`)
7170
|===
7271
7372
Fully specified class name of a custom
7473
link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`]
75-
implementation class or one of the predefined constants:
74+
implementation class or (since version 2.24.0) one of the predefined constants:
7675
7776
NoOp:: to disable the thread context,
7877
WebApp:: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
79-
CopyOnWrite:: a copy-on-write implementation,
8078
GarbageFree:: a garbage-free implementation.
8179
8280
// end::gcfree[]

‎src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-thread-context-simple-logger.adoc‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
////
2+
Licensed to the Apache Software Foundation (ASF) under one or more
3+
contributor license agreements. See the NOTICE file distributed with
4+
this work for additional information regarding copyright ownership.
5+
The ASF licenses this file to You under the Apache License, Version 2.0
6+
(the "License"); you may not use this file except in compliance with
7+
the License. You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
////
17+
[id=log4j2.disableThreadContext]
18+
== `log4j2.disableThreadContext`
19+
20+
[cols="1h,5"]
21+
|===
22+
| Env. variable | `LOG4J_DISABLE_THREAD_CONTEXT`
23+
| Type | `boolean`
24+
| Default value | `false`
25+
|===
26+
27+
If `true`, the `ThreadContext` stack and map are disabled.
28+
29+
[id=log4j2.disableThreadContextStack]
30+
== `log4j2.disableThreadContextStack`
31+
32+
[cols="1h,5"]
33+
|===
34+
| Env. variable | `LOG4J_DISABLE_THREAD_CONTEXT_STACK`
35+
| Type | `boolean`
36+
| Default value | `false`
37+
|===
38+
39+
If `true`, the `ThreadContext` stack is disabled.
40+
41+
[id=log4j2.disableThreadContextMap]
42+
== `log4j2.disableThreadContextMap`
43+
44+
[cols="1h,5"]
45+
|===
46+
| Env. variable | `LOG4J_DISABLE_THREAD_CONTEXT_MAP`
47+
| Type | `boolean`
48+
| Default value | `false`
49+
|===
50+
51+
If `true`, the `ThreadContext` map is disabled.
52+
53+
[id=log4j2.threadContextMap]
54+
== `log4j2.threadContextMap`
55+
56+
[cols="1h,5"]
57+
|===
58+
| Env. variable
59+
| `LOG4J_THREAD_CONTEXT_MAP`
60+
61+
| Type
62+
| link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`Class<? extends ThreadContextMap>`]
63+
64+
| Default value
65+
| link:../javadoc/log4j-api/org/apache/logging/log4j/spi/DefaultThreadContextMap.html[`DefaultThreadContextMap`]
66+
67+
|===
68+
69+
Fully specified class name of a custom
70+
link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`]
71+
implementation class.
72+
73+
[id=isThreadContextMapInheritable]
74+
== `log4j2.isThreadContextMapInheritable`
75+
76+
[cols="1h,5"]
77+
|===
78+
| Env. variable | `LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`
79+
| Type | `boolean`
80+
| Default value | `false`
81+
|===
82+
83+
If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
84+
85+
Note that, as explained in
86+
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.
87+

0 commit comments

Comments
 (0)