ramanathan1504 commented on code in PR #4230:
URL: https://github.com/apache/logging-log4j2/pull/4230#discussion_r4125741244
##########
src/site/antora/modules/ROOT/pages/manual/architecture.adoc:
##########
@@ -16,468 +16,848 @@
////
= Architecture
-== Main Components
-
-Log4j uses the classes shown in the diagram below.
-
-image:Log4jClasses.jpg[Log4j 2 Class Relationships,title="Log4j 2 Class
Relationships"]
-
-Applications using the Log4j 2 API will request a Logger with a specific
-name from the LogManager. The LogManager will locate the appropriate
-LoggerContext and then obtain the Logger from it. If the Logger must be
-created it will be associated with the LoggerConfig that contains either
-a) the same name as the Logger, b) the name of a parent package, or c)
-the root LoggerConfig. LoggerConfig objects are created from Logger
-declarations in the configuration. The LoggerConfig is associated with
-the Appenders that deliver the LogEvents.
-
-[id=logger-hierarchy]
-=== Logger Hierarchy
-
-The first and foremost advantage of any logging API over plain
-`System.out.println()` resides in its ability to disable certain log
-statements while allowing others to print unhindered. This capability
-assumes that the logging space, that is, the space of all possible
-logging statements, is categorized according to some developer-chosen
-criteria.
-
-In Log4j 1.x the Logger Hierarchy was maintained through a relationship
-between Loggers. In Log4j 2 this relationship no longer exists. Instead,
-the hierarchy is maintained in the relationship between LoggerConfig
-objects.
-
-Loggers and LoggerConfigs are named entities. Logger names are
-case-sensitive and they follow the hierarchical naming rule:
-
-Named Hierarchy::
-A LoggerConfig is said to be an _ancestor_ of another LoggerConfig if
-its name followed by a dot is a prefix of the _descendant_ logger
-name. A LoggerConfig is said to be a _parent_ of a _child_
-LoggerConfig if there are no ancestors between itself and the
-descendant LoggerConfig.
-
-For example, the LoggerConfig named `"com.foo"` is a parent of the
-LoggerConfig named `"com.foo.Bar"`. Similarly, `"java"` is a parent of
-`"java.util"` and an ancestor of `"java.util.Vector"`. This naming
-scheme should be familiar to most developers.
-
-The root LoggerConfig resides at the top of the LoggerConfig hierarchy.
-It is exceptional in that it always exists and it is part of every
-hierarchy. A Logger that is directly linked to the root LoggerConfig can
-be obtained as follows:
-
-[source,java]
-----
-Logger logger = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);
-----
-
-Alternatively, and more simply:
-
-[source,java]
-----
-Logger logger = LogManager.getRootLogger();
-----
-
-All other Loggers can be retrieved using the
-{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#getLogger(java.lang.String)[`LogManager.getLogger`]
-static method by passing the name of the desired Logger. Further
-information on the Logging API can be found in the
-xref:manual/api.adoc[Log4j API].
-
-=== LoggerContext
-
-The
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/LoggerContext.html[`LoggerContext`]
-acts as the anchor point for the Logging system. However, it is possible
-to have multiple active LoggerContexts in an application depending on
-the circumstances. More details on the LoggerContext are in the
-xref:manual/logsep.adoc[Log Separation] section.
-
-=== Configuration
-
-Every LoggerContext has an active
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html[`Configuration`].
-The Configuration contains all the Appenders, context-wide Filters,
-LoggerConfigs and contains the reference to the StrSubstitutor.
-During reconfiguration, two Configuration objects will exist. Once all Loggers
-have been redirected to the new Configuration, the old Configuration
-will be stopped and discarded.
-
-=== Logger
-
-As stated previously, Loggers are created by calling
-{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#getLogger(java.lang.String)[`LogManager.getLogger`].
-The Logger itself performs no direct actions. It simply has a name and
-is associated with a LoggerConfig. It extends
-{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/spi/AbstractLogger.html[`AbstractLogger`]
-and implements the required methods. As the configuration is modified
-Loggers may become associated with a different LoggerConfig, thus
-causing their behavior to be modified.
-
-Retrieving Loggers
-
-Calling the `LogManager.getLogger` method with the same name will always
-return a reference to the same Logger object.
-
-For example, in
-
-[source,java]
-----
-Logger x = LogManager.getLogger("wombat");
-Logger y = LogManager.getLogger("wombat");
-----
-
-`x` and `y` refer to _exactly_ the same Logger object.
-
-Configuration of the log4j environment is typically done at application
-initialization. The preferred way is by reading a configuration file.
-This is discussed in xref:manual/configuration.adoc[Configuration].
-
-Log4j makes it easy to name Loggers by _software component_. This can be
-accomplished by instantiating a Logger in each class, with the logger
-name equal to the fully qualified name of the class. This is a useful
-and straightforward method of defining loggers. As the log output bears
-the name of the generating Logger, this naming strategy makes it easy to
-identify the origin of a log message. However, this is only one
-possible, albeit common, strategy for naming loggers. Log4j does not
-restrict the possible set of loggers. The developer is free to name the
-loggers as desired.
-
-Since naming Loggers after their owning class is such a common idiom,
-the convenience method `LogManager.getLogger()` is provided to
-automatically use the calling class's fully qualified class name as the
-Logger name.
-
-Nevertheless, naming loggers after the class where they are located
-seems to be the best strategy known so far.
-
-[#loggerconfig]
-=== LoggerConfig
-
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/LoggerConfig.html[`LoggerConfig`]
-objects are created when Loggers are declared in the logging
-configuration. The LoggerConfig contains a set of Filters that must
-allow the LogEvent to pass before it will be passed to any Appenders. It
-contains references to the set of Appenders that should be used to
-process the event.
-
-==== Log Levels
-
-LoggerConfigs will be assigned a Log
-{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html[`Level`].
-The set of built-in levels includes ALL, TRACE, DEBUG, INFO, WARN, ERROR,
-FATAL, and OFF. Log4j 2 also supports
{log4j2-url}/manual/customloglevels.adoc[custom log
-levels]. Another mechanism for getting more granularity is to use
-{log4j2-url}/manual/markers.adoc[markers] instead. The OFF and ALL
-levels are not intended to be used on calls to the logging API.
-Specifying OFF in the configuration implies no logging events should
-match while specifying ALL would mean all events match, including custom
-events. However, OFF can be used on logging API calls in special cases
-where the event should always be logged regardless of the configuration.
-However, it is generally recommended that a Marker with a corresponding
-global Marker Filter be used instead.
-
-{logging-services-url}/log4j/1.x/manual.html[Log4j 1] and
-{logback-url}/manual/architecture.html#effectiveLevel[Logback]
-both have the concept of "Level Inheritance". In Log4j 2, Loggers and
-LoggerConfigs are two different objects so this concept is implemented
-differently. Each Logger references the appropriate LoggerConfig which
-in turn can reference its parent, thus achieving the same effect.
-
-Below are five tables with various assigned level values and the
-resulting levels that will be associated with each Logger. Note that in
-all these cases if the root LoggerConfig is not configured a default
-Level will be assigned to it.
-
-.Example 1
-[cols=",,,",options="header",]
-|====================================================================
-|Logger Name |Assigned LoggerConfig |LoggerConfig Level |Logger Level
+Log4j Core is the reference implementation of xref:manual/api.adoc[] and
composed of several components.
+In this section we will try to explain major pillars its architecture stands
on.
+An overview these major classes can be depicted as follows:
+
+[#architecture-diagram]
+.An overview of major classes and their relation
+[plantuml]
+....
+@startuml
+
+class LoggerContext {
+ Configuration config
+ Logger[] loggers
+ Logger getLogger(String name)
+}
+
+note left of LoggerContext {
+ Anchor for the logging system
+}
+
+LoggerContext --> "0..*" Logger
+
+package "Configuration" as c {
+
+ class Configuration {
+ Appender[] appenders
+ Filter[] filters
+ LoggerConfig[] loggerConfigs
+ LoggerConfig getLoggerConfig(String name)
+ StrSubstitutor substitutor
+ }
+
+ note left of Configuration
+ Encapsulates components compiled
+ from a user-provided configuration
+ file (e.g., `log4j2.xml`)
+ end note
+
+ Configuration --> Filter
+
+ Configuration --> "0..*" Appender
+
+ Configuration --> "0..*" LoggerConfig
+
+ Configuration --> StrSubstitutor
+
+ class Appender {
+ AbstractManager manager
+ Layout layout
+ Filter filter
+ void append(LogEvent)
+ }
+
+ Appender --> Layout
+
+ Appender --> Filter
+
+ class Layout {
+ byte[] encode(LogEvent)
+ }
+
+ class Filter {
+ Result filter(LogEvent)
+ }
+
+ note right of Filter
+ Note that a `Filter` can
+ be provided at 4 levels:
+ 1. `Configuration`
+ 2. `LoggerConfig`
+ 3. `AppenderControl`
+ 4. `Appender`
+ end note
+
+ class LoggerConfig {
+ AppenderControl[] appenderControls
+ Level level
+ Filter filter
+ void log(LogEvent)
+ }
+
+ LoggerConfig -[#green,thickness=6]-> "0..*" AppenderControl
+
+ LoggerConfig --> Filter
+
+ class AppenderControl {
+ Appender appender
+ Filter filter
+ void append(LogEvent)
+ }
+
+ note right of AppenderControl
+ Decorates an `Appender`
+ with a `Filter`
+ end note
+
+ AppenderControl -[#green,thickness=6]-> Appender
+
+ AppenderControl --> Filter
+
+ class StrSubstitutor {
+ Interpolator interpolator
+ String replace(String input)
+ }
+
+ note right of StrSubstitutor
+ Responsible for
+ property substitution
+ (e.g., `${env:USER}`)
+ end note
+
+ StrSubstitutor --> Interpolator
+
+ class Interpolator {
+ StrLookup[] lookups
+ String lookup(String input)
+ }
+
+ Interpolator --> "0..*" StrLookup
+
+ class StrLookup {
+ String lookup(String input)
+ }
+}
+
+LoggerContext --> Configuration
+
+class Logger {
+ void log(Level level, Message message)
+}
+
+note right of Logger
+ The main API entry point
+ users interact with
+end note
+
+Logger -[#green,thickness=6]-> LoggerConfig : delegates `log()`
+
+class AbstractManager {
+}
+
+Appender -[#green,thickness=6]-> AbstractManager
+
+@enduml
+....
+
+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 <<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.
+
+[#LoggerContext]
+== `LoggerContext`
+
+The
{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContext.html[`LoggerContext`]
acts as the anchor point for the logging system.
+It is associated with an active <<Configuration>> and is primarily responsible
for instantiating <<Logger>>s.
+
+[#LoggerContext-diagram]
+.`LoggerContext` and other directly related classes
+[plantuml]
+....
+@startuml
+
+class LoggerContext #line.bold {
+ Configuration config
+ Logger[] loggers
+ Logger getLogger(String name)
+}
+
+LoggerContext --> Configuration
+
+LoggerContext --> "0..*" Logger
+
+class Configuration {
+ Appender[] appenders
+ Filter[] filters
+ LoggerConfig[] loggerConfigs
+ LoggerConfig getLoggerConfig(String name)
+ StrSubstitutor substitutor
+}
+
+class Logger {
+ void log(Level level, Message message)
+}
+
+@enduml
+....
+
+In most cases, applications have a single global `LoggerContext`.
+Though in certain cases (e.g., Java EE applications), Log4j can be configured
to accommodate multiple ``LoggerContext``s.
+Refer to xref:manual/logsep.adoc[] for details.
+
+[#Configuration]
+== `Configuration`
+
+Every <<LoggerContext>> is associated with an active
link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html[`Configuration`].
+It models the configuration of all appenders, layouts, filters, loggers, and
contains the reference to <<StrSubstitutor>>.
+
+[#Configuration-diagram]
+.`Configuration` and other directly related classes
+[plantuml]
+....
+@startuml
+
+class LoggerContext {
+ Configuration config
+ Logger[] loggers
+ Logger getLogger(String name)
+}
+
+LoggerContext --> Configuration
+
+class Configuration #line.bold {
+ Appender[] appenders
+ Filter[] filters
+ LoggerConfig[] loggerConfigs
+ LoggerConfig getLoggerConfig(String name)
+ StrSubstitutor substitutor
+}
+
+Configuration --> "0..*" Filter
+
+Configuration --> "0..*" Appender
+
+Configuration --> "0..*" LoggerConfig
+
+Configuration --> StrSubstitutor
+
+class Appender {
+ Layout layout
+ void append(LogEvent)
+}
+
+class Filter {
+ Result filter(LogEvent)
+}
+
+class LoggerConfig {
+ AppenderRef[] appenderRefs
+ AppenderControl[] appenderControls
+ Level level
+ Filter filter
+ void log(LogEvent)
+}
+
+class StrSubstitutor {
+ Interpolator interpolator
+ String replace(String input)
+}
+@enduml
+....
+
+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]
Review Comment:
`configuration.adoc` links `architecture.adoc#logger-hierarchy` in three
places and `main` defines that id near the top of this page. Can the anchor
stay?
##########
src/site/antora/modules/ROOT/pages/manual/lookups.adoc:
##########
@@ -275,6 +275,12 @@ Do you want to use the values in Spring Boot's
`application.properties` file?
Use <<SpringBootLookup3>> instead.
====
+[#collection]
+== Collection
+
+Log4j bundles several predefined lookups to assist in several common
deployment use cases.
+Following sections explain all these in detail.
+
Review Comment:
`[#collection]` and `== Collection` are already on this page at line 131.
```suggestion
```
##########
src/site/antora/modules/ROOT/pages/manual/configuration.adoc:
##########
@@ -412,10 +406,9 @@ Between the two operations log events might be lost.
Overrides the logging level of {log4j2-url}/manual/status-logger.adoc[Status
Logger].
-[WARNING]
-====
-Since version `2.24.0`, this attribute is deprecated and should be replaced
with the
xref:manual/status-logger.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel]
configuration property instead.
-====
+WARNING: Since 2.24.0 this attribute is deprecated and should be replaced with
the
+{log4j2-url}/manual/systemproperties.html#log4j.sta.statusLoggerLevel[`log4j2.statusLoggerLevel`]
Review Comment:
The 2.x property id is `log4j2.statusLoggerLevel`.
```suggestion
{log4j2-url}/manual/systemproperties.html#log4j2.statusLoggerLevel[`log4j2.statusLoggerLevel`]
```
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -1545,8 +1544,9 @@ If your terminal supports 24-bit colors, you can specify:
[#ansi-windows]
==== ANSI styling on Windows
-ANSI escape sequences are supported natively on many platforms, but is
disabled by default in `cmd.exe` on Windows.
-To enable ANSI escape sequences, create a registry key of name
`HKEY_CURRENT_USER\Console\VirtualTerminalLevel` of type `DWORD` and set its
value to `0x1`.
+ANSI escape sequences are supported natively on many platforms, but not by
default on Windows.
+To enable ANSI support add the http://jansi.fusesource.org/[Jansi] dependency
to your application, and set
xref:manual/systemproperties.adoc#log4j.console.jansiEnabled[the
`log4j.console.jansiEnabled` system property] to `false`.
Review Comment:
`log4j.console.jansiEnabled` is not in the 3.x properties, and `main`
documents the Windows registry key instead. Can this paragraph stay as it is on
`main`?
##########
src/site/antora/modules/ROOT/pages/manual/extending.adoc:
##########
@@ -14,490 +14,151 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-= Extending Log4j
-Log4j provides numerous ways that it can be manipulated and extended.
-This section includes an overview of the various ways that are directly
-supported by the Log4j 3 implementation.
+= Extending
+
+Log4j provides numerous extension points to adapt it for custom needs.
+Several of such extension points are covered in the page of the associated
component:
+
+* Log4j API
+** {log4j2-url}/manual/customloglevels.html[Extending levels]
+** {log4j2-url}/manual/markers.html[Extending markers]
+** {log4j2-url}/manual/messages.html#extending[Extending messages]
+** {log4j2-url}/manual/thread-context.html#extending[Extending thread context]
+* Log4j Core
+** xref:manual/appenders.adoc#extending[Extending appenders]
+** xref:manual/filters.adoc#extending[Extending filters]
+** xref:manual/layouts.adoc#extending[Extending layouts]
+*** xref:manual/json-template-layout.adoc#extending[Extending JSON Template
Layout]
+*** xref:manual/pattern-layout.adoc#extending[Extending Pattern Layout]
+** xref:manual/lookups.adoc#extending[Extending lookups]
+
+This section guides you on the rest of the Log4j extension points.
+
+[#mechanisms]
+== Extension mechanisms
+
+Log4j allows extensions primarily using following mechanisms:
+
+[#Custom_Plugins]
+=== Plugins
+
+include::partial$manual/plugin-preliminaries.adoc[]
+
+[#bindings]
+=== Bindings
+
+The Log4j plugin system was enhanced in 3.0 to support arbitrary bindings for
xref:manual/dependencyinjection.adoc[dependency injection].
+Many shared components in Log4j could be configured via system properties or
similar to include a fully qualified class name to use.
+Using custom bindings, however, these custom classes can be configured as code.
+Default bindings are configured in
{project-github-url}/log4j-core/src/main/java/org/apache/logging/log4j/core/impl/CoreDefaultBundle.java[`CoreDefaultBundle`].
+Custom bindings can be installed by defining a
link:../javadoc/log4j-plugins/org/apache/logging/log4j/plugins/di/spi/ConfigurableInstanceFactoryPostProcessor.html[`ConfigurableInstanceFactoryPostProcessor`]
service class which invokes `ConfigurableInstanceFactory::registerBundle` to
register the bundle class containing the bindings.
+This approach is more portable than the legacy approach of using system
properties to define the classes as it removes ambiguity of `ClassLoader`
ownership and other details of modules and similar runtimes.
+
+[#service-loader]
+=== ``ServiceLoader``s
+
+https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/ServiceLoader.html[`ServiceLoader`]
is a simple service-provider loading facility baked into the Java platform
itself.
+Log4j uses ``ServiceLoader``s for extending places where
+
+* The service needs to be implementation agnostic.
+As a result, <<Custom_Plugins,the Log4j plugin system>> cannot be used, since
it is provided by the logging implementation, i.e., Log4j Core.
+For instance, this is why
{log4j2-url}/manual/thread-context.html#extending[extending Thread Context],
which is a Log4j API component, works using ``ServiceLoader``s.
+
+* The service needs to be loaded before <<Custom_Plugins,the Log4j plugin
system>>.
+For instance, this is why <<Provider,extending `Provider`>> works using
``ServiceLoader``s.
+
+Refer to
https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/ServiceLoader.html[the
`ServiceLoader` documentation] for details.
+
+[#system-properties]
+=== System properties
+
+Log4j uses system properties to determine the fully-qualified class name
(FQCN) to load for extending a certain functionality.
+For instance, <<MessageFactory, extending `MessageFactory2`>> works using
system properties.
+
+[WARNING]
+====
+Loading a class using _only_ its FQCN can result in unexpected behaviour when
there are multiple class loaders.
+====
+
+[#points]
+== Extension points
+
+In this section we will guide you on certain Log4j extension points that are
not covered elsewhere.
+
+[#Provider]
+=== `Provider`
+
+link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider.html[`Provider`]
is the anchor contract binding Log4j API to an implementation.
+For instance, it has been implemented by Log4j Core, Log4j-to-JUL bridge, and
Log4j-to-SLF4J bridge modules.
+
+Under the hood,
link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`LogManager`]
locates a `Provider` implementation using <<service-loader,the `ServiceLoader`
mechanism>>, and delegates invocations to it.
+Hence, you can extend it by providing a
`org.apache.logging.log4j.spi.Provider` implementation in the form of a
`ServiceLoader`.
+
+Having multiple ``Provider``s in the classpath is strongly discouraged.
+A specific provider can be <<bindings,bound>> using a custom bundle class if
Log4j Core is also available.
+Alternatively, you can use
xref:manual/systemproperties.adoc#log4j.provider[the `log4j.provider` property]
to explicitly select one.
Review Comment:
`log4j.provider` has no entry in `systemproperties.adoc` and the name is not
in `log4j-api`, `log4j-kit` or `log4j-core`. Is the property still there under
another name?
##########
src/site/antora/modules/ROOT/pages/manual/plugins.adoc:
##########
@@ -14,245 +14,267 @@
See the License for the specific language governing permissions and
limitations under the License.
////
+
= Plugins
-Log4j 1.x allowed for extension by requiring class attributes on most of
-the configuration declarations. In the case of some elements, notably
-the PatternLayout, the only way to add new pattern converters was to
-extend the PatternLayout class and add them via code. One goal of Log4j
-2 is to make extending it extremely easy through the use of plugins.
-
-In Log4j 3.x, a plugin is declared by adding a `@Plugin` and `@Namespace`
annotation to the class declaration.
-During initialization the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html[`Configuration`]
-will invoke the `PluginRegistry`
-to load the built-in Log4j plugins as well as any custom plugins. The
-`Injector` locates plugins by looking in the following places:
-
-1. Plugin collection classes on the classpath that are loaded by
java.util.ServiceLoader.
-These classes are generated automatically during the build (more details
below).
-2. (OSGi only) Serialized plugin listing files in each active OSGi
-bundle. A `BundleListener` is added on activation to continue checking
-new bundles after `log4j-plugins` has started. Bundles must register their
plugin collection
-class as an OSGi service.
-3. Serialized plugin listing files on the classpath. These files were
generated by
-the plugin annotation processor in Log4j 2 2.x. These are processed to allow
-compatibility.
-
-When multiple plugins use the same case-insensitive `name` within the same
plugin category, then which one is selected is determined first by the presence
of `@PluginOrder` annotations and then by the previously described plugin
loading order.
-For example, to override the `File` plugin which is provided by the built-in
`FileAppender` class, you would need to place your plugin in a JAR file in the
CLASSPATH ahead of`log4j-core.jar`.
-This is not recommended; plugin name collisions will cause a warning to be
emitted.
-Note that in an OSGi environment, the order that bundles are scanned for
plugins generally follows the same order that bundles were installed into the
framework.
-See
https://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()[`getBundles()`]
and
https://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html[`SynchronousBundleListener`].
-In short, name collisions are even more unpredictable in an OSGi environment
without additional `@PluginOrder` usage.
-
-Plugin collection classes are generated by an annotation processor contained
-in the log4j-plugins artifact which will automatically scan your code for
-Log4j 2 plugins and generate a Java source file that references all the
-located plugins. It will also generate a
-META-INF/services/org.apache.logging.log4j.plugins.model.PluginService
-file in compliance with java.util.ServiceLoader.
-There is nothing extra that needs to be done to enable this;
-the Java compiler will automatically pick up the annotation processor on
-the class path unless you explicitly disable it.
-
-If annotation processing is disabled plugins may still be registered by either
-[loweralpha]
-.. manually providing a class that extends
`org.apache.logging.log4j.plugins.model.PluginService`
-and identifies all the plugins and also declaring a
-`META-INF/services/org.apache.logging.log4j.plugins.model.PluginService` file
-that provides the fully qualified name of the implemented class or
-.. adding another compiler pass to the build process that
-only handles annotation processing using the Log4j 2 annotation
-processor class,
-`org.apache.logging.log4j.plugin.processor.PluginProcessor`.
-To do this using Apache Maven, add the following execution to your
-_maven-compiler-plugin_ (version 2.2 or higher) build plugin:
-
-[source,xml]
+Log4j plugin system is the de facto extension mechanism embraced by various
Log4j Core components.
+Plugins make it possible for extensible components to _receive_ feature
implementations without any explicit links in between.
+It is analogous to a
https://en.wikipedia.org/wiki/Dependency_injection[dependency injection]
framework, but curated for xref:manual/dependencyinjection.adoc[Log4j-specific
needs].
+
+[NOTE]
+====
+Log4j plugin system is implemented by Log4j Core, the logging implementation.
+It is deliberately not a part of the Log4j API to keep the logging API
footprint small.
+====
+
+[TIP]
+====
+Did you know about *xref:plugin-reference.adoc[], the documentation extracted
from the source code* of all predefined Log4j plugins?
+Like Javadoc, but specialized for plugins!
+====
+
+In this section we will give an overview of the Log4j plugin system by
answering certain questions:
+
+. <<#declare-plugin,How can you declare a plugin?>>
+. <<#core,How can you declare a plugin that needs to be represented in a Log4j
configuration file?>>
+. <<#plugin-registry,How can you register your plugin to Log4j?>>
+. <<#plugin-discovery,How does Log4j discover plugins?>>
+. <<#plugin-load,How can you load other plugins in a plugin?>>
+
+[#declare-plugin]
+== Declaring plugins
+
+A class can be declared as a plugin by adding a
link:../javadoc/log4j-plugins/org/apache/logging/log4j/plugins/Plugin.html[`@Plugin`]
annotation and a
link:../javadoc/log4j-plugins/org/apache/logging/log4j/plugins/Configurable.html[`@Configurable`]
annotation.
+
+`@Plugin::value`::
+Name of the plugin.
+If left unspecified, this defaults to the simple class name of the annotated
class.
+This name should be unique within all plugins sharing the same `@Namepsace`
(in this case, the `@Configurable` annotation uses the `Core` namespace).
+The plugin name is matched using case-insensitive equality.
+
+`@Namespace::value`::
+Plugins are grouped together in namespaces where they can be identified by
name.
+Namespaces are case-sensitive.
+Typical plugins use the `Core` namespace which is handled by the
`@Configurable` annotation.
+
+`@Configurable::elementType` (deprecated)::
+We don't recommend the usage of `elementType` anymore.
+Existing usages are kept for backward compatibility reasons with the legacy
configuration syntax: `<appender type="ConsoleAppender"`.
+
+See
{project-github-url}/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/LowerLookup.java[`LowerLookup.java`]
(a xref:manual/lookups.adoc[lookup] for lower-casing its input) for a simple
example.
+
+.Click to read more on *name collision* and *overriding an existing plugin*
+[%collapsible]
+====
+The name of a plugin given in either `@Plugin::value` or derived from the
simple name of the annotated class should be distinct within the same
`@Namespace::value`.
+In case of a name collision, a warning will be emitted, and the plugin
<<plugin-discovery,discovery order>> will determine the effective plugin.
+For example, to override the `File` plugin which is provided by the built-in
xref:manual/appenders.adoc#FileAppender[File Appender], you would need to place
your plugin in a JAR file in the classpath ahead of Log4j Core JAR.
+In an OSGi environment, the order that bundles are scanned for plugins
generally follows the same order that bundles were installed into the
framework; see
https://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()[`getBundles()`]
and
https://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html[`SynchronousBundleListener`].
+In short, name collisions are even more unpredictable in an OSGi environment.
+====
+
+[#core]
+== Declaring plugins represented in a configuration file
+
+If your plugin needs to be represented by an element in a configuration file
(such as an xref:manual/appenders.adoc[appender],
xref:manual/layouts.adoc[layout], xref:manual/api.adoc#loggers[logger], or
xref:manual/filters.adoc[filter]), following requirements must be met:
Review Comment:
`api.adoc` has no `loggers` anchor on `main`.
```suggestion
If your plugin needs to be represented by an element in a configuration file
(such as an xref:manual/appenders.adoc[appender],
xref:manual/layouts.adoc[layout], xref:manual/api.adoc[logger], or
xref:manual/filters.adoc[filter]), following requirements must be met:
```
##########
src/site/antora/modules/ROOT/pages/manual/plugins.adoc:
##########
@@ -14,245 +14,267 @@
See the License for the specific language governing permissions and
limitations under the License.
////
+
= Plugins
-Log4j 1.x allowed for extension by requiring class attributes on most of
-the configuration declarations. In the case of some elements, notably
-the PatternLayout, the only way to add new pattern converters was to
-extend the PatternLayout class and add them via code. One goal of Log4j
-2 is to make extending it extremely easy through the use of plugins.
-
-In Log4j 3.x, a plugin is declared by adding a `@Plugin` and `@Namespace`
annotation to the class declaration.
-During initialization the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html[`Configuration`]
-will invoke the `PluginRegistry`
-to load the built-in Log4j plugins as well as any custom plugins. The
-`Injector` locates plugins by looking in the following places:
-
-1. Plugin collection classes on the classpath that are loaded by
java.util.ServiceLoader.
-These classes are generated automatically during the build (more details
below).
-2. (OSGi only) Serialized plugin listing files in each active OSGi
-bundle. A `BundleListener` is added on activation to continue checking
-new bundles after `log4j-plugins` has started. Bundles must register their
plugin collection
-class as an OSGi service.
-3. Serialized plugin listing files on the classpath. These files were
generated by
-the plugin annotation processor in Log4j 2 2.x. These are processed to allow
-compatibility.
-
-When multiple plugins use the same case-insensitive `name` within the same
plugin category, then which one is selected is determined first by the presence
of `@PluginOrder` annotations and then by the previously described plugin
loading order.
-For example, to override the `File` plugin which is provided by the built-in
`FileAppender` class, you would need to place your plugin in a JAR file in the
CLASSPATH ahead of`log4j-core.jar`.
-This is not recommended; plugin name collisions will cause a warning to be
emitted.
-Note that in an OSGi environment, the order that bundles are scanned for
plugins generally follows the same order that bundles were installed into the
framework.
-See
https://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()[`getBundles()`]
and
https://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html[`SynchronousBundleListener`].
-In short, name collisions are even more unpredictable in an OSGi environment
without additional `@PluginOrder` usage.
-
-Plugin collection classes are generated by an annotation processor contained
-in the log4j-plugins artifact which will automatically scan your code for
-Log4j 2 plugins and generate a Java source file that references all the
-located plugins. It will also generate a
-META-INF/services/org.apache.logging.log4j.plugins.model.PluginService
-file in compliance with java.util.ServiceLoader.
-There is nothing extra that needs to be done to enable this;
-the Java compiler will automatically pick up the annotation processor on
-the class path unless you explicitly disable it.
-
-If annotation processing is disabled plugins may still be registered by either
-[loweralpha]
-.. manually providing a class that extends
`org.apache.logging.log4j.plugins.model.PluginService`
-and identifies all the plugins and also declaring a
-`META-INF/services/org.apache.logging.log4j.plugins.model.PluginService` file
-that provides the fully qualified name of the implemented class or
-.. adding another compiler pass to the build process that
-only handles annotation processing using the Log4j 2 annotation
-processor class,
-`org.apache.logging.log4j.plugin.processor.PluginProcessor`.
-To do this using Apache Maven, add the following execution to your
-_maven-compiler-plugin_ (version 2.2 or higher) build plugin:
-
-[source,xml]
+Log4j plugin system is the de facto extension mechanism embraced by various
Log4j Core components.
+Plugins make it possible for extensible components to _receive_ feature
implementations without any explicit links in between.
+It is analogous to a
https://en.wikipedia.org/wiki/Dependency_injection[dependency injection]
framework, but curated for xref:manual/dependencyinjection.adoc[Log4j-specific
needs].
+
+[NOTE]
+====
+Log4j plugin system is implemented by Log4j Core, the logging implementation.
+It is deliberately not a part of the Log4j API to keep the logging API
footprint small.
+====
+
+[TIP]
+====
+Did you know about *xref:plugin-reference.adoc[], the documentation extracted
from the source code* of all predefined Log4j plugins?
+Like Javadoc, but specialized for plugins!
+====
+
+In this section we will give an overview of the Log4j plugin system by
answering certain questions:
+
+. <<#declare-plugin,How can you declare a plugin?>>
+. <<#core,How can you declare a plugin that needs to be represented in a Log4j
configuration file?>>
+. <<#plugin-registry,How can you register your plugin to Log4j?>>
+. <<#plugin-discovery,How does Log4j discover plugins?>>
+. <<#plugin-load,How can you load other plugins in a plugin?>>
+
+[#declare-plugin]
+== Declaring plugins
+
+A class can be declared as a plugin by adding a
link:../javadoc/log4j-plugins/org/apache/logging/log4j/plugins/Plugin.html[`@Plugin`]
annotation and a
link:../javadoc/log4j-plugins/org/apache/logging/log4j/plugins/Configurable.html[`@Configurable`]
annotation.
+
+`@Plugin::value`::
+Name of the plugin.
+If left unspecified, this defaults to the simple class name of the annotated
class.
+This name should be unique within all plugins sharing the same `@Namepsace`
(in this case, the `@Configurable` annotation uses the `Core` namespace).
+The plugin name is matched using case-insensitive equality.
+
+`@Namespace::value`::
+Plugins are grouped together in namespaces where they can be identified by
name.
+Namespaces are case-sensitive.
+Typical plugins use the `Core` namespace which is handled by the
`@Configurable` annotation.
+
+`@Configurable::elementType` (deprecated)::
+We don't recommend the usage of `elementType` anymore.
+Existing usages are kept for backward compatibility reasons with the legacy
configuration syntax: `<appender type="ConsoleAppender"`.
+
+See
{project-github-url}/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/LowerLookup.java[`LowerLookup.java`]
(a xref:manual/lookups.adoc[lookup] for lower-casing its input) for a simple
example.
+
+.Click to read more on *name collision* and *overriding an existing plugin*
+[%collapsible]
+====
+The name of a plugin given in either `@Plugin::value` or derived from the
simple name of the annotated class should be distinct within the same
`@Namespace::value`.
+In case of a name collision, a warning will be emitted, and the plugin
<<plugin-discovery,discovery order>> will determine the effective plugin.
+For example, to override the `File` plugin which is provided by the built-in
xref:manual/appenders.adoc#FileAppender[File Appender], you would need to place
your plugin in a JAR file in the classpath ahead of Log4j Core JAR.
Review Comment:
`FileAppender` moved to `appenders/file.adoc` on `main`.
```suggestion
For example, to override the `File` plugin which is provided by the built-in
xref:manual/appenders/file.adoc#FileAppender[File Appender], you would need to
place your plugin in a JAR file in the classpath ahead of Log4j Core JAR.
```
##########
src/site/antora/modules/ROOT/pages/manual/customconfig.adoc:
##########
@@ -14,372 +14,236 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-= Programmatic Configuration
+= Programmatic configuration
-Log4j 2 provides a few ways for applications to create their own
-programmatic configuration:
+Next to xref:manual/configuration.adoc[configuration files], Log4j Core can be
configured programmatically too.
+In this page, we will explore utilities helping with programmatic
configuration and demonstrate how they can be leveraged for certain use cases.
-* Specify a custom `ConfigurationFactory` to start Log4j with a
-programmatic configuration
-* Use the `Configurator` to replace the configuration after Log4j started
-* Initialize Log4j with a combination of a configuration file and
-programmatic configuration
-* Modify the current `Configuration` after initialization
+[#prelim]
+== Preliminaries
+
+To begin with, we strongly encourage you to check out the
xref:manual/architecture.adoc[] page first.
+Let's repeat some basic definitions of particular interest:
+
+xref:manual/architecture.adoc#LoggerContext[`LoggerContext`]::
+It is the anchor of the logging system.
+Generally there is one, statically-accessible, global `LoggerContext` for most
applications.
+But there can be multiple ``LoggerContext``s, for instance, to use in tests,
in Java EE web applications, etc.
+
+xref:manual/architecture.adoc#Configuration[`Configuration`]::
+It encapsulates a Log4j Core configuration (properties, appenders, loggers,
etc.) and is associated with a `LoggerContext`.
+
+[#tooling]
+== Tooling
+
+For programmatic configuration, Log4j Core essentially provides the following
tooling:
+
+<<ConfigurationBuilder>>:: for declaratively creating a `Configuration`
+
+<<Configurator>>:: for associating a `Configuration` with a `LoggerContext`
+
+<<ConfigurationFactory>>:: for registering a `Configuration` factory to
xref:manual/configuration.adoc[the configuration file mechanism]
+
+In short, we will create ``Configuration``s using `ConfigurationBuilder`, and
activate them using `Configurator`.
[#ConfigurationBuilder]
-== The ConfigurationBuilder API
-
-Starting with release 2.4, Log4j provides a `ConfigurationBuilder` and a
-set of component builders that allow a `Configuration` to be created
-fairly easily. Actual configuration objects like `LoggerConfig` or
-`Appender` can be unwieldy; they require a lot of knowledge about Log4j
-internals which makes them difficult to work with if all you want is to
-create a `Configuration`.
-
-The new `ConfigurationBuilder` API (in the
-`org.apache.logging.log4j.core.config.builder.api` package) allows users
-to create Configurations in code by constructing component
-_definitions_. There is no need to work directly with actual
-configuration objects. Component definitions are added to the
-`ConfigurationBuilder`, and once all the definitions have been collected
-all the actual configuration objects (like Loggers and Appenders) are
-constructed.
-
-`ConfigurationBuilder` has convenience methods for the base components
-that can be configured such as Loggers, Appenders, Filter, Properties,
-etc. However, Log4j 2's plugin mechanism means that users can create any
-number of custom components. As a trade-off, the `ConfigurationBuilder`
-API provides only a limited number of "strongly typed" convenience
-methods like `newLogger()`, `newLayout()` etc. The generic
-`builder.newComponent()` method can be used if no convenience method
-exists for the component you want to configure.
-
-For example, the builder does not know what sub-components can be
-configured on specific components such as the RollingFileAppender vs.
-the RoutingAppender. To specify a triggering policy on a
-RollingFileAppender you would use builder.newComponent().
-
-Examples of using the `ConfigurationBuilder` API are in the sections that
-follow.
+=== `ConfigurationBuilder`
-[#ConfigurationFactory]
-== Understanding ConfigurationFactory
-
-During initialization, Log4j 2 will search for available
-xref:manual/extending.adoc#ConfigurationFactory[ConfigurationFactories] and
-then select the one to use. The selected `ConfigurationFactory` creates
-the `Configuration` that Log4j will use. Here is how Log4j finds the
-available ConfigurationFactories:
-
-1. A system property named `log4j2.configurationFactory` can be set
-with the name of the ConfigurationFactory to be used.
-2. `ConfigurationFactory.setConfigurationFactory(ConfigurationFactory)`
-can be called with the instance of the `ConfigurationFactory` to be used.
-This must be called before any other calls to Log4j.
-3. A `ConfigurationFactory` implementation can be added to the classpath
-and configured as a plugin in the "ConfigurationFactory" category. The
-`@Order` annotation can be used to specify the relative priority when
-multiple applicable ConfigurationFactories are found.
-
-ConfigurationFactories have the concept of "supported types", which
-basically maps to the file extension of the configuration file that the
-ConfigurationFactory can handle. If a configuration file location is
-specified, ConfigurationFactories whose supported type does not include
-"*" or the matching file extension will not be used.
-
-[#Example]
-== Initialize Log4j Using ConfigurationBuilder with a Custom
ConfigurationFactory
-
-One way to programmatically configure Log4j 2 is to create a custom
-`ConfigurationFactory` that uses the
-<<ConfigurationBuilder,`ConfigurationBuilder`>> to create a
-Configuration. The below example overrides the `getConfiguration()`
-method to return a `Configuration` created by the `ConfigurationBuilder`.
-This will cause the `Configuration` to automatically be hooked into Log4j
-when the `LoggerContext` is created. In the example below, because it
-specifies a supported type of "*" it will override any configuration
-files provided.
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[`ConfigurationBuilder`]
interface models a fluent API to programmatically create
link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html[`Configuration`]s.
+If you have ever created a xref:manual/configuration.adoc[Log4j Core
configuration file], consider `ConfigurationBuilder` as a convenience utility
to model the very same declarative configuration structure programmatically.
+
+Let's show `ConfigurationBuilder` usage with an example.
+Consider the following Log4j Core configuration file:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example
{antora-examples-url}/manual/customconfig/ConfigurationBuilder/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/customconfig/ConfigurationBuilder/log4j2.xml[lines=24..34,indent=0]
+----
+
+JSON::
++
+.Snippet from an example
{antora-examples-url}/manual/customconfig/ConfigurationBuilder/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/customconfig/ConfigurationBuilder/log4j2.json[lines=3..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example
{antora-examples-url}/manual/customconfig/ConfigurationBuilder/log4j2.yaml[`log4j2.yaml`]
+[source,yaml]
+----
+include::example$manual/customconfig/ConfigurationBuilder/log4j2.yaml[lines=19..-1,indent=0]
+----
+Properties::
++
+.Snippet from an example
{antora-examples-url}/manual/customconfig/ConfigurationBuilder/log4j2.properties[`log4j2.properties`]
+[source,properties]
+----
+include::example$manual/customconfig/ConfigurationBuilder/log4j2.properties[lines=17..-1]
+----
+====
+
+Above Log4j Core configuration can be programmatically built using
`ConfigurationBuilder` as follows:
+
+.Snippet from an example
{antora-examples-url}/manual/customconfig/Usage.java[`Usage.java`]
[source,java]
----
-@Namespace(ConfigurationFactory.NAMESPACE)
-@Plugin
-@Order(50)
-public class CustomConfigurationFactory extends ConfigurationFactory {
-
- static Configuration createConfiguration(final String name,
ConfigurationBuilder<BuiltConfiguration> builder) {
- builder.setConfigurationName(name);
- builder.setStatusLevel(Level.ERROR);
- builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT,
Filter.Result.NEUTRAL).
- addAttribute("level", Level.DEBUG));
- AppenderComponentBuilder appenderBuilder =
builder.newAppender("Stdout", "CONSOLE").
- addAttribute("target", ConsoleAppender.Target.SYSTEM_OUT);
- appenderBuilder.add(builder.newLayout("PatternLayout").
- addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
- appenderBuilder.add(builder.newFilter("MarkerFilter",
Filter.Result.DENY,
- Filter.Result.NEUTRAL).addAttribute("marker", "FLOW"));
- builder.add(appenderBuilder);
- builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG).
- add(builder.newAppenderRef("Stdout")).
- addAttribute("additivity", false));
-
builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout")));
- return builder.build();
- }
-
- @Override
- public Configuration getConfiguration(final LoggerContext loggerContext,
final ConfigurationSource source) {
- return getConfiguration(loggerContext, source.toString(), null);
- }
-
- @Override
- public Configuration getConfiguration(final LoggerContext loggerContext,
final String name, final URI configLocation) {
- ConfigurationBuilder<BuiltConfiguration> builder =
newConfigurationBuilder();
- return createConfiguration(name, builder);
- }
-
- @Override
- protected String[] getSupportedTypes() {
- return new String[] {"*"};
- }
-}
+include::example$manual/customconfig/Usage.java[tag=createConfiguration,indent=0]
----
+<1> The default `ConfigurationBuilder` instance is obtained using
link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilderFactory.html#newConfigurationBuilder()[`ConfigurationBuilderFactory.newConfigurationBuilder()`]
static method
+<2> Add the appender along with the layout
+<3> Add the root logger along with a level and appender reference
+<4> Create the configuration, but *don't initialize* it
++
+[TIP]
+====
+It is a good practice to not initialize ``Configuration``s when they are
constructed.
+This task should ideally be delegated to <<Configurator>>.
+====
+
+`ConfigurationBuilder` has convenience methods for the base components that
can be configured such as loggers, appenders, filters, properties, etc.
+Though there are cases where the provided convenience methods fall short of:
-As of version 2.7, the `ConfigurationFactory.getConfiguration()` methods
-take an additional `LoggerContext` parameter.
+* Custom xref:manual/plugins.adoc#core[plugins that are declared to be
represented in a configuration]
+* Custom subcomponents (e.g., a
xref:manual/appenders.adoc#TriggeringPolicies[triggering policy] for
xref:manual/appenders.adoc#RollingFileAppender[`RollingFileAppender`])
Review Comment:
Both anchors live in `appenders/rolling-file.adoc` on `main`, and the
triggering policy one is `TriggeringPolicy`.
```suggestion
* Custom subcomponents (e.g., a
xref:manual/appenders/rolling-file.adoc#TriggeringPolicy[triggering policy] for
xref:manual/appenders/rolling-file.adoc#RollingFileAppender[`RollingFileAppender`])
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
