Skip to content

Commit fc51ccd

Browse files
ppkarwaszppkarwasz
committed
Update documentation
1 parent db7df88 commit fc51ccd

File tree

8 files changed

+118
-12
lines changed

8 files changed

+118
-12
lines changed

‎log4j-api-test/pom.xml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,6 @@
111111
<dependency>
112112
<groupId>org.assertj</groupId>
113113
<artifactId>assertj-core</artifactId>
114-
<scope>test</scope>
115114
</dependency>
116115
<!-- Required for JSON support -->
117116
<dependency>

‎log4j-core/src/main/java/org/apache/logging/log4j/core/impl/package-info.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
* Log4j 2 private implementation classes.
1919
*/
2020
@Export
21-
@Version("2.23.0")
21+
@Version("2.24.0")
2222
package org.apache.logging.log4j.core.impl;
2323

2424
import org.osgi.annotation.bundle.Export;

‎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: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -120,9 +120,25 @@ executor.submit(() -> {
120120
[#config]
121121
== Configuration
122122
123-
You can configure thread context using following properties:
123+
Since the thread context is inherently linked to the logging implementation, its configuration options depend on the logging implementation used:
124124
125-
include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+1]
125+
Simple Logger::
126+
+
127+
See xref:manual/simple-logger.adoc#thread-context[Thread context configuration of Simple Logger].
128+
129+
Log4j Core::
130+
+
131+
See xref:manual/systemproperties.adoc#properties-thread-context[Thread context configuration of Log4j Core].
132+
133+
SLF4J implementations (Logback)::
134+
+
135+
All `ThreadContext` method calls are translated into equivalent
136+
https://www.slf4j.org/api/org/slf4j/MDC.html[`org.slf4j.MDC`]
137+
method calls.
138+
139+
JUL::
140+
+
141+
All `ThreadContext` method calls are a no-op.
126142
127143
[#extending]
128144
== 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)