You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by pk...@apache.org on 2024/06/13 09:58:16 UTC
(logging-log4j2) 01/01: Split "Configuration" page (`2.x` branch)
This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch doc/2.x/configuration-split
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 5d25e794810147d183d4888e6b88c3c4446e0f42
Author: Piotr P. Karwasz <pi...@karwasz.org>
AuthorDate: Thu Jun 13 11:56:29 2024 +0200
Split "Configuration" page (`2.x` branch)
This splits the configuration page into:
- a short intro to the "Configuration" chapter,
- a page dedicated entirely to the "Configuration file".
---
src/site/antora/modules/ROOT/nav.adoc | 4 +-
.../modules/ROOT/pages/manual/config-intro.adoc | 33 +++++++++
.../modules/ROOT/pages/manual/configuration.adoc | 84 +++++++++-------------
3 files changed, 68 insertions(+), 53 deletions(-)
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
index a3221fef6a..d9807c03de 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -38,8 +38,8 @@
*** xref:manual/thread-context.adoc[]
** xref:manual/messages.adoc[]
** xref:manual/flowtracing.adoc[]
-* Configuration
-** xref:manual/configuration.adoc[Configuration file]
+* xref:manual/config-intro.adoc[]
+** xref:manual/configuration.adoc[]
** xref:manual/systemproperties.adoc[]
** xref:manual/customconfig.adoc[]
** xref:manual/appenders.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/manual/config-intro.adoc b/src/site/antora/modules/ROOT/pages/manual/config-intro.adoc
new file mode 100644
index 0000000000..90bf892d86
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/manual/config-intro.adoc
@@ -0,0 +1,33 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[id=configuration]
+= Configuration
+
+Logging is a standard method for monitoring the health of an application and diagnosing problems that may arise within it.
+Even moderately sized applications can contain thousands of logging statements.
+
+To decide which of these statements will be logged and where, users need to configure Log4j Core in one of two ways:
+
+* through a xref:manual/configuration.adoc[].
+Since version 2.0, the configuration file format has been considered part of the public API and has remained stable across significant version upgrades.
+
+* through xref:manual/customconfig.adoc[Programmatic Configuration], which provides a larger spectrum of possible customizations but might require code changes during version upgrades.
+
+[NOTE]
+====
+To prevent a chicken-and-egg problem, users can only supply some configuration options (e.g., the configuration file location) through xref:manual/systemproperties.adoc[configuration properties].
+====
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
index 05cc479f30..89e96cdaef 100644
--- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
@@ -14,26 +14,8 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-[id=configuration]
-= Configuration
-
-Logging is a standard method for monitoring the health of an application and diagnosing problems that may arise within it.
-Even moderately sized applications can contain thousands of logging statements.
-
-To decide which of these statements will be logged and where, users need to configure Log4j Core in one of two ways:
-
-* through a <<configuration-file>>.
-Since version 2.0, the configuration file format has been considered part of the public API and has remained stable across significant version upgrades.
-
-* through xref:manual/customconfig.adoc[Programmatic Configuration], which provides a larger spectrum of possible customizations but might require code changes during version upgrades.
-
-[NOTE]
-====
-To prevent a chicken-and-egg problem, users can only supply some configuration options (e.g., the configuration file location) through xref:manual/systemproperties.adoc[configuration properties].
-====
-
[#configuration-file]
-== Configuration file
+= Configuration file
Users can configure Log4j Core using different file formats.
The `log4j-core` artifact includes XML, JSON, YAML, and Java properties formats factories.
@@ -47,11 +29,11 @@ include::partial$configuration-file-format-deps.adoc[]
The format of the configuration file changed between Log4j{nbsp}1 and Log4j{nbsp}2.
Files in the Log4j{nbsp}1 format are ignored by default.
-To enable partial support for old configuration formats, see xref:manual/migration.adoc#enabling-the-log4j-1-x-bridge[Enabling the Log4j{nbsp}1 bridge].
+To enable partial support for old configuration formats, see xref:manual/migration.adoc#ConfigurationCompatibility[Log4j 1 to Log4j 2 bridge].
====
[id=automatic-configuration]
-=== [[AutomaticConfiguration]] Configuration file location
+== [[AutomaticConfiguration]] Configuration file location
Upon initialization of a new logger context, Log4j assigns it a context name and scans the following **classpath** locations for a configuration file:
@@ -118,7 +100,7 @@ See xref:manual/systemproperties.adoc#log4j2.configurationFile[log4j2.configurat
====
[id=configuration-syntax]
-=== [[ConfigurationSyntax]] Syntax
+== [[ConfigurationSyntax]] Syntax
The Log4j runtime is composed of xref:manual/plugins.adoc[plugins], which are like beans in the Spring Framework and Java EE.
Appenders, layouts, filters, configuration loaders, and similar components are all accessed as plugins.
@@ -252,7 +234,7 @@ Nested components use the assigned ID for sorting purposes only.
See also <<format-specific-notes>> for exceptions to the rules above.
[id=main-configuration-elements]
-=== Main configuration elements
+== Main configuration elements
Log4j Core's logging pipeline is quite complex (see xref:manual/architecture.adoc[Architecture]), but most users only require these elements:
@@ -345,7 +327,7 @@ Using the above configuration, the list of appenders that will be used for each
|===
[id=additional-configuration-elements]
-=== Additional configuration elements
+== Additional configuration elements
A Log4j Core configuration file can also contain these configuration elements:
@@ -374,14 +356,14 @@ Scripts are a container for JSR 223 scripts that users can use in other Log4j co
For details, see xref:manual/scripts.adoc[Scripts configuration].
[id=global-configuration-attributes]
-=== Global configuration attributes
+== Global configuration attributes
The main `Configuration` element has a set of attributes that can be used to tune how the configuration file is used.
The principal attributes are listed below.
See xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Configuration[Plugin reference] for a complete list.
[id=configuration-attribute-monitorInterval]
-==== [[AutomaticReconfiguration]] `monitorInterval`
+=== [[AutomaticReconfiguration]] `monitorInterval`
[cols="1h,5"]
|===
@@ -408,7 +390,7 @@ To modify these options during a reconfiguration, you also need to change the re
====
[id=configuration-attribute-status]
-==== `status`
+=== `status`
[cols="1h,5"]
|===
@@ -426,12 +408,12 @@ Since version `2.24.0`, this attribute is deprecated and should be replaced with
====
[id=configuration-elements-filters]
-==== Filters
+=== Filters
See xref:manual/filters.adoc#filters[Filters] for additional filtering capabilities that can be applied to the global configuration object.
[id=configuring-loggers]
-=== [[Loggers]] Loggers
+== [[Loggers]] Loggers
Log4j 2 contains multiple types of logger configurations that can be added to the `Loggers` element of the configuration:
@@ -544,7 +526,7 @@ h| Appenders used
In the following part of this section, we explain in detail all the available options for logger configurations:
[id=logger-attributes-name]
-==== `name`
+=== `name`
[cols="1h,5"]
|===
@@ -560,7 +542,7 @@ Specifies the name of the logger configuration.
Since loggers are usually named using fully qualified class names, this value usually contains the fully qualified name of a class or a package.
[id=logger-attributes-additivity]
-==== [[Additivity]] `additivity`
+=== [[Additivity]] `additivity`
[cols="1h,5"]
|===
@@ -573,7 +555,7 @@ If `true` (default), all the messages this logger receives will also be transmit
xref:manual/architecture.adoc#logger-hierarchy[parent logger]).
[id=logger-attributes-level]
-==== `level`
+=== `level`
[cols="1h,5"]
|===
@@ -595,7 +577,7 @@ Log events that are more specific than this setting will be filtered out.
See also xref:manual/filters.adoc#filters[Filters] if you require additional filtering.
[id=logger-attributes-includeLocation]
-==== `includeLocation`
+=== `includeLocation`
[cols="1h,5"]
|===
@@ -623,14 +605,14 @@ methods.
See xref:manual/layouts.adoc#LocationInformation[Location information] for more details.
[id=logger-elements-appenderrefs]
-==== Appender references
+=== Appender references
Loggers use appender references to list the appenders to deliver log events.
See <<configuring-appenderrefs>> below for more details.
[id=logger-elements-properties]
-==== Additional context properties
+=== Additional context properties
Loggers can emit additional context data that will be integrated with other context data sources such as xref:manual/thread-context.adoc[ThreadContext].
@@ -676,12 +658,12 @@ include::example$manual/configuration/logger-properties.properties[tag=loggers]
====
[id=logger-elements-filters]
-==== Filters
+=== Filters
See xref:manual/filters.adoc#filters[Filters] for additional filtering capabilities that can be applied to a logger configuration.
[id=configuring-appenderrefs]
-=== Appender references
+== Appender references
Many Log4j components, such as loggers, use appender references to designate which appenders will be used to deliver their events.
@@ -690,7 +672,7 @@ Unlike in Log4j 1, where appender references were simple pointers, in Log4j 2, t
Appender references can have the following configuration attributes and elements:
[id=appenderref-attributes-name]
-==== `ref`
+=== `ref`
[cols="1h,5"]
|===
@@ -700,7 +682,7 @@ Appender references can have the following configuration attributes and elements
Specifies the name of the appender to use.
[id=appenderref-attributes-level]
-==== `level`
+=== `level`
[cols="1h,5"]
|===
@@ -711,12 +693,12 @@ Specifies the level threshold that a log event must have to be logged.
Log events that are more specific than this setting will be filtered out.
[id=appenderrefs-elements-filters]
-==== Filters
+=== Filters
See xref:manual/filters.adoc#filters[Filters] for additional filtering capabilities that can be applied to a logger configuration.
[id=property-substitution]
-=== [[PropertySubstitution]]Property substitution
+== [[PropertySubstitution]]Property substitution
Log4j provides a simple and extensible mechanism to reuse values in the configuration file using `$\{name}` expressions, such as those used in Bash, Ant or Maven.
@@ -919,7 +901,7 @@ Therefore, the value of the `logging.file` property will be:
=====
[id=lazy-property-substitution]
-==== Lazy property substitution
+=== Lazy property substitution
For most attributes, property substitution is performed only once at **configuration time**, but there are two categories of exceptions to this rule:
@@ -976,7 +958,7 @@ Therefore, the dollar `$` sign needs to be escaped.
<2> All the attributes inside the `File` element have a **deferred** evaluation, therefore they need only one `$` sign.
[id=arbiters]
-=== [[Arbiters]] Arbiters
+== [[Arbiters]] Arbiters
While property substitution allows using the same configuration file in multiple deployment environments, sometimes changing the values of configuration attributes is not enough.
@@ -1071,7 +1053,7 @@ include::example$manual/configuration/arbiters-select.properties[tag=select]
<2> Otherwise, a JSON template layout will be used.
[#CompositeConfiguration]
-=== Composite Configuration
+== Composite Configuration
Log4j allows multiple configuration files to be used at the same time by specifying them as a list of comma-separated file paths or URLs in the
xref:manual/systemproperties.adoc#log4j2.configurationFile[log4j2.configurationFile]
@@ -1107,18 +1089,18 @@ Appender references on a logger are aggregated, and those in later configuration
The strategy merges filters on loggers using the rule above.
[id=format-specific-notes]
-=== Format specific notes
+== Format specific notes
[id=xml-features]
-==== XML format
+=== XML format
[id=xml-global-configuration-attributes]
-===== Global configuration attributes
+==== Global configuration attributes
The XML format supports the following additional attributes on the `Configuration` element.
[id=configuration-attribute-schema]
-====== `schema`
+===== `schema`
[cols="1h,5"]
|===
@@ -1129,7 +1111,7 @@ The XML format supports the following additional attributes on the `Configuratio
Specifies the path to a classpath resource containing an XML schema.
[id=configuration-attribute-strict]
-====== `strict`
+===== `strict`
[cols="1h,5"]
|===
@@ -1143,7 +1125,7 @@ If set to `true,` all configuration files will be checked against the XML schema
This setting also enables "XML strict mode" and allows one to specify an element's **plugin type** through a `type` attribute instead of the tag name.
[id=xinclude]
-===== [[XInlcude]] XInclude
+==== [[XInlcude]] XInclude
XML configuration files can include other files with
https://www.w3.org/TR/xinclude/[XInclude].
@@ -1172,7 +1154,7 @@ include::example$manual/configuration/xinclude-loggers.xml[lines=1;18..-1]
----
[id=java-properties-features]
-==== Java properties format
+=== Java properties format
[TIP]
====