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/07/01 07:09:53 UTC
(logging-log4j2) branch doc/2.x/extending updated (136506e882 -> 0a09e700ed)
This is an automated email from the ASF dual-hosted git repository.
vy pushed a change to branch doc/2.x/extending
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
from 136506e882 Merge remote-tracking branch 'origin/2.x' into doc/2.x/extending
new f8a5534496 Place `Reconfiguration reliability` under `Configuration`
new 0a09e700ed Advise against programmatically modifying components
The 2 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:
.../modules/ROOT/pages/manual/architecture.adoc | 113 ++++++++++-----------
.../modules/ROOT/pages/manual/customconfig.adoc | 7 +-
2 files changed, 58 insertions(+), 62 deletions(-)
(logging-log4j2) 01/02: Place `Reconfiguration reliability` under `Configuration`
Posted by vy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch doc/2.x/extending
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit f8a5534496bef6de7c01e30514fe589825b31605
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Mon Jul 1 09:06:30 2024 +0200
Place `Reconfiguration reliability` under `Configuration`
---
.../modules/ROOT/pages/manual/architecture.adoc | 113 ++++++++++-----------
1 file changed, 52 insertions(+), 61 deletions(-)
diff --git a/src/site/antora/modules/ROOT/pages/manual/architecture.adoc b/src/site/antora/modules/ROOT/pages/manual/architecture.adoc
index 3c9b032d25..b97b63502b 100644
--- a/src/site/antora/modules/ROOT/pages/manual/architecture.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/architecture.adoc
@@ -167,70 +167,13 @@ At a really high level,
* A <<LoggerContext>>, the composition anchor, gets created in combination with a <<Configuration>>.
Both can be created either directly (i.e., programmatically) or indirectly at first interaction with Log4j.
* `LoggerContext` creates <<Logger>>s that users interact with for logging purposes.
-* <<Appender>> delivers a
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`]
-to a target (file, socket, database, etc.) and typically uses a <<Layout>> to encode log events and an
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/AbstractManager.html[`AbstractManager`]
-to handle the lifecycle of the target resource.
+* <<Appender>> delivers a link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`] to a target (file, socket, database, etc.) and typically uses a <<Layout>> to encode log events and an <<AbstractManager>> to handle the lifecycle of the target resource.
* <<LoggerConfig>> encapsulates configuration for a `Logger`, as `AppenderControl` and `AppenderRef` for ``Appender``s.
* <<Configuration>> is equipped with <<StrSubstitutor>> to allow property substitution in `String`-typed values.
* A typical `log()` call triggers a chain of invocations through classes `Logger`, `LoggerConfig`, `AppenderControl`, `Appender`, and `AbstractManager` in order – this is depicted using green arrows in xref:architecture-diagram[xrefstyle=short].
Following sections examine this interplay in detail.
-[#reconfiguration]
-== Reconfiguration reliability
-
-The main motivation for such an architecture is reliability to configuration changes.
-When a reconfiguration event occurs, two `Configuration` instances are active at the same time.
-Threads that already started processing a log event will either:
-
-* continue logging to the old configuration, if execution already reached the `LoggerConfig` class,
-* or switch to the new configuration.
-
-The service that manages the reconfiguration process is called
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ReliabilityStrategy.html[`ReliabilityStrategy`]
-and it decides:
-
-* when should ``Logger``s switch to the new configuration,
-* when should the old configuration be stopped.
-
-.Overview of the reconfiguration process
-[plantuml]
-....
-@startuml
-left to right direction
-
-package LoggerContext {
- object Logger
-
- package "New Configuration" as c2 {
- object "LoggerConfig" as lc2
- object "AppenderControl" as ac2
- object "Appender" as app2
- }
-
- package "Old Configuration" as c1 {
- object "LoggerConfig" as lc1
- object "AppenderControl" as ac1
- object "Appender" as app1
- }
-}
-
-object AbstractManager
-
-Logger ..> lc1
-lc1 --> ac1
-ac1 --> app1
-app1 --> AbstractManager
-
-Logger --> lc2
-lc2 --> ac2
-ac2 --> app2
-app2 --> AbstractManager
-@enduml
-....
-
[#LoggerContext]
== `LoggerContext`
@@ -332,13 +275,61 @@ class StrSubstitutor {
@enduml
....
-During reconfiguration, two `Configuration` instances will be present.
-Once all ``Logger``s have been redirected to the new `Configuration`, the old one will be stopped and discarded.
-
Configuration of Log4j Core is typically done at application initialization.
The preferred way is by reading a xref:manual/configuration.adoc[configuration file], but it can also be done xref:manual/customconfig.adoc[programmatically].
This is further discussed in xref:manual/config-intro.adoc[].
+[#reconfiguration]
+=== Reconfiguration reliability
+
+The main motivation for the existing architecture is the reliability to configuration changes.
+When a reconfiguration event occurs, two `Configuration` instances are active at the same time.
+Threads that already started processing a log event will either:
+
+* continue logging to the old configuration, if execution already reached the `LoggerConfig` class,
+* or switch to the new configuration.
+
+The service that manages the reconfiguration process is called link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ReliabilityStrategy.html[`ReliabilityStrategy`] and it decides:
+
+* when should ``Logger``s switch to the new configuration,
+* when should the old configuration be stopped.
+
+.Overview of the reconfiguration process
+[plantuml]
+....
+@startuml
+left to right direction
+
+package LoggerContext {
+ object Logger
+
+ package "New Configuration" as c2 {
+ object "LoggerConfig" as lc2
+ object "AppenderControl" as ac2
+ object "Appender" as app2
+ }
+
+ package "Old Configuration" as c1 {
+ object "LoggerConfig" as lc1
+ object "AppenderControl" as ac1
+ object "Appender" as app1
+ }
+}
+
+object AbstractManager
+
+Logger ..> lc1
+lc1 --> ac1
+ac1 --> app1
+app1 --> AbstractManager
+
+Logger --> lc2
+lc2 --> ac2
+ac2 --> app2
+app2 --> AbstractManager
+@enduml
+....
+
[#Logger]
== `Logger`
(logging-log4j2) 02/02: Advise against programmatically modifying components
Posted by vy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch doc/2.x/extending
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 0a09e700ed95b9839e4f1112bafcb94c69fc643f
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Mon Jul 1 09:10:21 2024 +0200
Advise against programmatically modifying components
---
src/site/antora/modules/ROOT/pages/manual/customconfig.adoc | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/src/site/antora/modules/ROOT/pages/manual/customconfig.adoc b/src/site/antora/modules/ROOT/pages/manual/customconfig.adoc
index fae7af0698..25a89d93f9 100644
--- a/src/site/antora/modules/ROOT/pages/manual/customconfig.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/customconfig.adoc
@@ -216,6 +216,12 @@ include::partial$manual/composite-configuration.adoc[tag=how]
[#Hybrid]
=== [[AddingToCurrent]] [[AppendingToWritersAndOutputStreams]] Modifying configuration components
+[WARNING]
+====
+*We strongly advise against programmatically modifying components of a configuration!*
+This section will explain what it is, and why you should avoid it.
+====
+
It is unfortunately common that users modify components (appenders, filters, etc.) of a configuration programmatically as follows:
[source,java]
@@ -229,7 +235,6 @@ config.addAppender(appender);
updateLoggers(appender, config);
----
-*We strongly advise you to avoid programmatically modifying components of a configuration!*
This approach is prone several problems:
* Your code relies on Log4j Core internals which don't have any backward compatibility guarantees.