This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch doc/2.x/links in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 06f19c1d3dfb50663ff65e5008f428569c3e4e04 Author: Piotr P. Karwasz <[email protected]> AuthorDate: Tue May 28 09:56:55 2024 +0200 Fix broken internal links Fix links to `runtime-dependencies.adoc` and similar by inlining the content into the page. --- pom.xml | 7 +++ src/site/antora/antora.tmpl.yml | 1 + src/site/antora/antora.yml | 1 + src/site/antora/modules/ROOT/pages/faq.adoc | 3 +- .../antora/modules/ROOT/pages/getting-started.adoc | 4 +- .../antora/modules/ROOT/pages/log4j-1.2-api.adoc | 11 +++- .../antora/modules/ROOT/pages/log4j-couchdb.adoc | 2 +- .../antora/modules/ROOT/pages/log4j-docker.adoc | 5 +- .../antora/modules/ROOT/pages/log4j-flume-ng.adoc | 5 +- .../antora/modules/ROOT/pages/log4j-iostreams.adoc | 9 +++- .../modules/ROOT/pages/log4j-jakarta-web.adoc | 1 - .../modules/ROOT/pages/log4j-spring-boot.adoc | 5 +- .../pages/log4j-spring-cloud-config-client.adoc | 5 +- .../antora/modules/ROOT/pages/log4j-taglib.adoc | 1 - src/site/antora/modules/ROOT/pages/log4j-web.adoc | 1 - .../modules/ROOT/pages/manual/appenders.adoc | 9 ++-- .../modules/ROOT/pages/manual/compatibility.adoc | 2 +- .../modules/ROOT/pages/manual/configuration.adoc | 5 +- .../modules/ROOT/pages/manual/installation.adoc | 3 +- .../ROOT/pages/manual/json-template-layout.adoc | 2 +- .../antora/modules/ROOT/pages/manual/layouts.adoc | 60 +++++++++++++++++++--- .../antora/modules/ROOT/pages/manual/logsep.adoc | 3 +- .../antora/modules/ROOT/pages/manual/lookups.adoc | 2 +- .../antora/modules/ROOT/pages/manual/messages.adoc | 6 +-- .../modules/ROOT/pages/manual/status-logger.adoc | 3 +- .../manual/dependencies-log4j-1.2-api.adoc} | 32 ++++++++---- .../manual/dependencies-log4j-csv.adoc} | 32 ++++++++---- .../manual/dependencies-log4j-layout-json.adoc} | 32 ++++++++---- .../dependencies-log4j-layout-template-json.adoc} | 32 ++++++++---- .../manual/dependencies-log4j-layout-xml.adoc} | 32 ++++++++---- .../manual/dependencies-log4j-layout-yaml.adoc} | 32 ++++++++---- 31 files changed, 242 insertions(+), 106 deletions(-) diff --git a/pom.xml b/pom.xml index 8bbee8266f..197ffa7dc0 100644 --- a/pom.xml +++ b/pom.xml @@ -331,6 +331,7 @@ <!-- Skipping `maven-site-plugin` globally. --> <maven.site.skip>true</maven.site.skip> <maven.site.deploy.skip>true</maven.site.deploy.skip> + <site-commons-csv.version>1.11.0</site-commons-csv.version> <site-commons-logging.version>1.3.2</site-commons-logging.version> <site-disruptor.version>4.0.0</site-disruptor.version> <site-jackson.version>2.17.1</site-jackson.version> @@ -717,6 +718,12 @@ <!-- Other dependencies --> + <dependency> + <groupId>org.apache.commons</groupId> + <artifactId>commons-csv</artifactId> + <version>${site-commons-csv.version}</version> + </dependency> + <dependency> <groupId>commons-logging</groupId> <artifactId>commons-logging</artifactId> diff --git a/src/site/antora/antora.tmpl.yml b/src/site/antora/antora.tmpl.yml index 034e5deeb2..32b48b1ac6 100644 --- a/src/site/antora/antora.tmpl.yml +++ b/src/site/antora/antora.tmpl.yml @@ -48,6 +48,7 @@ asciidoc: logging-services-url: "https://logging.apache.org"; lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor"; # Dependency versions + commons-csv-version: "${site-commons-csv.version}" commons-logging-version: "${site-commons-logging.version}" disruptor-version: "${site-disruptor.version}" jackson-version: "${site-jackson.version}" diff --git a/src/site/antora/antora.yml b/src/site/antora/antora.yml index f5ebbf65fc..f1ce58368e 100644 --- a/src/site/antora/antora.yml +++ b/src/site/antora/antora.yml @@ -48,6 +48,7 @@ asciidoc: logging-services-url: "https://logging.apache.org"; lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor/"; # Dependency versions + commons-csv-version: "1.2.3-commons-csv" commons-logging-version: "1.2.3-commons-logging" disruptor-version: "1.2.3-disruptor" jackson-version: "1.2.3-jackson" diff --git a/src/site/antora/modules/ROOT/pages/faq.adoc b/src/site/antora/modules/ROOT/pages/faq.adoc index 418d0dc229..c7df6c65dd 100644 --- a/src/site/antora/modules/ROOT/pages/faq.adoc +++ b/src/site/antora/modules/ROOT/pages/faq.adoc @@ -201,7 +201,8 @@ The problem with custom logger wrappers is that they have a different FQCN than The solution is to provide the correct FQCN. The easiest way to do this is to let Log4j generate the logger wrapper for you. Log4j comes with a Logger wrapper generator tool. -This tool was originally meant to support custom log levels and is documented xref:manual/customloglevels.adoc#CustomLoggers[here]. +This tool was originally meant to support custom log levels and was moved to the +link:/log4j/transform/latest/index.html[Log4j Transform subproject]. The generated logger code will take care of the FQCN. [#proguard-rules] diff --git a/src/site/antora/modules/ROOT/pages/getting-started.adoc b/src/site/antora/modules/ROOT/pages/getting-started.adoc index 7c414463f6..e723d99446 100644 --- a/src/site/antora/modules/ROOT/pages/getting-started.adoc +++ b/src/site/antora/modules/ROOT/pages/getting-started.adoc @@ -413,7 +413,7 @@ See xref:#config-test[] For tests, prefer a human-readable layout with increased verbosity. While it is not recommended to use the `PatternLayout` in production for security reasons, it is a good choice for tests. -The xref:manual/layouts.adoc#PatternLayout[Pattern Layout] is used for formatting strings in a specific way. +The xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is used for formatting strings in a specific way. In the below case, it will include the timestamp, thread name, log level, class name, and the message and print it to the Console. Very similar to the earlier configuration, the `<logger>` defines what should be logged on @@ -446,7 +446,7 @@ Save the following XML document to `src/**test**/resources/log4j2-test.xml`. </Configuration> ---- -<1> xref:manual/layouts.adoc#PatternLayout[Pattern Layout] is used for a human-readable layout. +<1> xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is used for a human-readable layout. <2> Increased logging verbosity for the `com.mycompany` package. [#next] diff --git a/src/site/antora/modules/ROOT/pages/log4j-1.2-api.adoc b/src/site/antora/modules/ROOT/pages/log4j-1.2-api.adoc index edc33ee147..7ec6131be4 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-1.2-api.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-1.2-api.adoc @@ -58,7 +58,16 @@ The following Log4j 1.x methods will behave differently when the Log4j 2 Core mo If log4j-core is not present location information will not be accurate in calls using the Log4j 1.2 API. The config package which attempts to convert Log4j 1.x configurations to Log4j 2 is not supported without Log4j 2. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. +[NOTE] +====== +In order to use the Log4j 1.2 Bridge, additional dependencies are required: + +.Runtime dependencies +[%collapsible,id=log4j-1.2-api-deps] +===== +include::partial$manual/dependencies-log4j-1.2-api.adoc[] +===== +====== == Usage diff --git a/src/site/antora/modules/ROOT/pages/log4j-couchdb.adoc b/src/site/antora/modules/ROOT/pages/log4j-couchdb.adoc index 276ef5647f..05cb0ae7c0 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-couchdb.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-couchdb.adoc @@ -43,4 +43,4 @@ https://couchdb.apache.org/[Apache CouchDB] is supported through the http://www. == Requirements The CouchDB Appender is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. + diff --git a/src/site/antora/modules/ROOT/pages/log4j-docker.adoc b/src/site/antora/modules/ROOT/pages/log4j-docker.adoc index c4eb104814..669d0bf63c 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-docker.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-docker.adoc @@ -40,5 +40,6 @@ Log4j Docker provides access to the following container attributes: Attributes may be accessed by adding `${docker:containerId}` to the configuration. Note that docker variables are only resolved once during logging initialization so they shouldn't be referenced with more than one `$` character. -== Requirements Log4j Docker requires Log4j Core, Log4j API and a minimum of Java 8. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. +== Requirements + +Log4j Docker requires Log4j Core, Log4j API and a minimum of Java 8. diff --git a/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc b/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc index a829d0994c..4fb6ff80bb 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc @@ -225,5 +225,6 @@ The following is a sample pom file for Maven that can be used as a template for </project> ---- -== Requirements The Flume Appender requires the Log4J 2 API. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. +== Requirements + +The Flume Appender requires the Log4J 2 API and implementation. diff --git a/src/site/antora/modules/ROOT/pages/log4j-iostreams.adoc b/src/site/antora/modules/ROOT/pages/log4j-iostreams.adoc index 66e1f90170..3edabf279a 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-iostreams.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-iostreams.adoc @@ -18,13 +18,18 @@ Licensed to the Apache Software Foundation (ASF) under one or more == Log4j IOStreams -The IOStreams component is a link:javadoc/log4j-api/index.html[Log4j API] extension that provides numerous classes from http://docs.oracle.com/javase/6/docs/api/java/io/package-summary.html[`java.io`] that can either write to a link:javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`] while writing to another `OutputStream` or `Writer`, or the contents read by an `InputStream` or `Reader` can be http://www.eaipatterns.com/WireTap.html[wiretapped] by a `Logger`. +The IOStreams component is a +xref:manual/api.adoc[] +extension that provides numerous classes from +http://docs.oracle.com/javase/{java-target-version}/docs/api/java/io/package-summary.html[`java.io`] +that can either write to a +link:javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`] +while writing to another `OutputStream` or `Writer`, or the contents read by an `InputStream` or `Reader` can be http://www.eaipatterns.com/WireTap.html[wiretapped] by a `Logger`. == Requirements The Log4j IOStreams API extension requires the Log4j 2 API. This component was introduced in Log4j 2.1. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. == Usage diff --git a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc b/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc index 9bc18d982d..8384e864ed 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc @@ -25,4 +25,3 @@ See the user manual page on xref:manual/webapp.adoc[Web Applications and JSPs] f == Requirements The Web module requires Servlet 5.0 at minimum and is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. diff --git a/src/site/antora/modules/ROOT/pages/log4j-spring-boot.adoc b/src/site/antora/modules/ROOT/pages/log4j-spring-boot.adoc index eacd5211f3..7a60326f5c 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-spring-boot.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-spring-boot.adoc @@ -39,7 +39,9 @@ would set the Log4j applicationName property to the value of spring.application. === Spring Property Source Log4j uses property sources when resolving properties it uses internally. -This support allows most of Log4j's xref:manual/configuration.adoc#SystemProperties[System Properties] to be specified in the Spring Configuration. +This support allows most of Log4j's +xref:manual/systemproperties.adoc[] +to be specified in the Spring Configuration. However, some properties that are only referenced during the first Log4j initialization, such as the property Log4j uses to allow the default Log4j implementation to be chosen, would not be available. === Spring Profile Arbiter @@ -78,4 +80,3 @@ Below is an example: == Requirements The Log4j 2 Spring Cloud Configuration integration has a dependency on Log4j 2 API, Log4j 2 Core, and Spring Boot versions 2.0.3.RELEASE or 2.1.1.RELEASE or later versions it either release series. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. diff --git a/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc b/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc index ce8e4b31ca..7d364bdb31 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc @@ -128,9 +128,10 @@ If more extensive authentication is required an `AuthorizationProvider` can be i xref:manual/systemproperties.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in log4j2.component.properties or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` or `logging.auth.authorizationProvider` key. -For the properties required by TLS configuration see xref:manual/configuration.adoc#transport-security[the Transport Security configuration]. +For the properties required by TLS configuration see +xref:manual/systemproperties +.adoc#properties-transport-security[the Transport Security configuration]. == Requirements The Log4j 2 Spring Cloud Configuration integration has a dependency on Log4j 2 API, Log4j 2 Core, and Spring Cloud Configuration versions 2.0.3.RELEASE or 2.1.1.RELEASE or later versions it either release series. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. diff --git a/src/site/antora/modules/ROOT/pages/log4j-taglib.adoc b/src/site/antora/modules/ROOT/pages/log4j-taglib.adoc index b86a2e2b20..ff074eb08e 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-taglib.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-taglib.adoc @@ -26,7 +26,6 @@ However, the "category" attribute from Jakarta has become the "logger" attribute == Requirements The Log4j Tag Library requires at least Servlet 2.5 (or Java EE 5), at least JSP 2.1 (or Java EE 5), and is dependent on the Log4j 2 API. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. [IMPORTANT] ==== diff --git a/src/site/antora/modules/ROOT/pages/log4j-web.adoc b/src/site/antora/modules/ROOT/pages/log4j-web.adoc index ef365413ea..be17df4352 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-web.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-web.adoc @@ -25,4 +25,3 @@ See the user manual page on xref:manual/webapp.adoc[Web Applications and JSPs] f == Requirements The Web module requires Servlet 2.5 at minimum and is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc index 095dc3475a..c93b35ff66 100644 --- a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc @@ -81,7 +81,7 @@ By default, AsyncAppender uses https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ArrayBlockingQueue.html[`java.util.concurrent.ArrayBlockingQueue`] which does not require any external libraries. Note that multi-threaded applications should exercise care when using this appender as such: the blocking queue is susceptible to lock contention and our -xref:manual/performance.adoc#asyncLogging[tests showed] performance may become worse when more threads are logging concurrently. +xref:manual/performance.adoc#async[tests showed] performance may become worse when more threads are logging concurrently. Consider using xref:manual/async.adoc[lock-free Async Loggers] for optimal performance. @@ -863,7 +863,7 @@ As of Log4j 2.11.0, JDBC support has moved from the existing module `log4j-core` to the new module `log4j-jdbc`. The JDBC Appender configured with a `DataSource` requires JNDI support so as of release 2.17.1 this appender will not function unless `log4j2.enableJndiJdbc=true` is configured as a system property or environment variable. -See the xref:manual/configuration.adoc#enableJndiJdbc[enableJndiJdbc] system property. +See the xref:manual/systemproperties.adoc#log4j2.enableJndiJdbc[log4j2.enableJndiJdbc] system property. The JDBCAppender writes log events to a relational database table using standard JDBC. It can be configured to obtain JDBC connections using a JNDI `DataSource` or a custom factory method. @@ -2236,7 +2236,7 @@ The RandomAccessFileAppender is similar to the standard link:#FileAppender[FileAppender] except it is always buffered (this cannot be switched off) and internally it uses a `ByteBuffer + RandomAccessFile` instead of a `BufferedOutputStream`. We saw a 20-200% performance improvement compared to FileAppender with "bufferedIO=true" in our -xref:manual/performance.adoc#whichAppender[measurements]. +measurements. Similar to the FileAppender, RandomAccessFileAppender uses a RandomAccessFileManager to perform the file I/O. While RandomAccessFileAppender from different Configurations cannot be shared, the RandomAccessFileManagers can be if the Manager is accessible. For example, two web applications in a servlet container can have their configuration and safely write to the same file if Log4j is in a ClassLoader that is common to both of them. @@ -3405,8 +3405,7 @@ Below is a sample configuration that uses a RollingFileAppender and defines diff The RollingRandomAccessFileAppender is similar to the standard link:#RollingFileAppender[RollingFileAppender] except it is always buffered (this cannot be switched off) and internally it uses a `ByteBuffer + RandomAccessFile` instead of a `BufferedOutputStream`. -We saw a 20-200% performance improvement compared to RollingFileAppender with "bufferedIO=true" in our -xref:manual/performance.adoc#whichAppender[measurements]. +We saw a 20-200% performance improvement compared to RollingFileAppender with "bufferedIO=true" in our measurements. The `RollingRandomAccessFileAppender` writes to the file named in the fileName parameter and rolls the file over according to the TriggeringPolicy and the RolloverPolicy. Similar to the RollingFileAppender, RollingRandomAccessFileAppender uses a RollingRandomAccessFileManager to perform the file I/O and perform the rollover. diff --git a/src/site/antora/modules/ROOT/pages/manual/compatibility.adoc b/src/site/antora/modules/ROOT/pages/manual/compatibility.adoc index 8f2f0aff3d..1383161987 100644 --- a/src/site/antora/modules/ROOT/pages/manual/compatibility.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/compatibility.adoc @@ -19,4 +19,4 @@ Licensed to the Apache Software Foundation (ASF) under one or more == Compatibility with Log4j 1 -See the xref:manual/migration.adoc#Log4j1.2Bridge[Log4j 1.x bridge (log4j-1.2-api)] section of the Log4j 1.x Migration page. +See the xref:manual/migration.adoc#Log4j12Bridge[Log4j 1.x bridge (log4j-1.2-api)] section of the Log4j 1.x Migration page. diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc index 8aff3a4281..1072ad9c03 100644 --- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc @@ -418,7 +418,7 @@ To modify these options during a reconfiguration, you also need to change the re |=== | Type | link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[LEVEL] | Status | **DEPRECATED** -| Default value (since 2.24.0) | xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] +| Default value (since 2.24.0) | xref:manual/status-logger.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] | Default value (before 2.24.0) | value of `log4j2.defaultStatusLevel` |=== @@ -426,7 +426,8 @@ Overrides the logging level of xref:manual/status-logger.adoc[]. [WARNING] ==== -Since version `2.24.0`, this attribute is deprecated and should be replaced with the xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] configuration property instead. +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. ==== [id=configuration-elements-filters] diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc index cf84dac6c7..2e1bcd9ff5 100644 --- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc @@ -630,7 +630,8 @@ rootLogger.appenderRef.0.ref = CONSOLE ---- ==== -<1> While xref:manual/layouts.adoc#PatternLayout[Pattern Layout] is a good first choice and preferable for tests, we recommend using a structured format such as xref:manual/json-template-layout.adoc[] for production deployments. +<1> While xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is a good first choice and preferable for tests, we recommend +using a structured format such as xref:manual/json-template-layout.adoc[] for production deployments. To use these formats, the following additional dependencies are required: diff --git a/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc index 57f6ab2498..c600488a67 100644 --- a/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc @@ -1171,7 +1171,7 @@ pattern = "pattern" -> string stackTraceEnabled = "stackTraceEnabled" -> boolean ---- -Resolver delegating to xref:manual/layouts.adoc#PatternLayout[`PatternLayout`]. +Resolver delegating to xref:manual/layouts.adoc#pattern-layout[`PatternLayout`]. The default value of `stackTraceEnabled` is inherited from the parent `JsonTemplateLayout`. diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc index 45f7c19f38..11cead0fa4 100644 --- a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc @@ -154,7 +154,16 @@ Produces a CSV record with the following fields: 0,1441617184044,DEBUG,main,"one=1, two=2, three=3",org.apache.logging.log4j.spi.AbstractLogger,,,,org.apache.logging.log4j.core.layout.CsvLogEventLayoutTest.testLayout(CsvLogEventLayoutTest.java:98),{},[] .... -Additional xref:runtime-dependencies.adoc[runtime dependencies] are required for using CSV layouts. +[NOTE] +====== +Additional runtime dependencies are required for using CSV layouts: + +.Runtime dependencies +[%collapsible,id=log4j-csv-deps] +===== +include::partial$manual/dependencies-log4j-csv.adoc[] +===== +====== [#GELFLayout] == GELF Layout @@ -409,7 +418,16 @@ To include any custom field in the output, use the following syntax: Custom fields are always last, in the order they are declared. The values support xref:manual/lookups.adoc[lookups]. -Additional xref:runtime-dependencies.adoc[runtime dependencies] are required for using JsonLayout. +[NOTE] +====== +Additional runtime dependencies are required for using `JsonLayout`: + +.Runtime dependencies +[%collapsible,id=log4j-layout-json-deps] +===== +include::partial$manual/dependencies-log4j-layout-json.adoc[] +===== +====== [#JSONTemplateLayout] == JSON Template Layout @@ -513,6 +531,17 @@ JSON Template Layout will render JSON documents as follows: } ---- +[NOTE] +====== +Additional runtime dependencies are required for using JSON Template Layout: + +.Runtime dependencies +[%collapsible,id=log4j-layout-template-json-deps] +===== +include::partial$manual/dependencies-log4j-layout-template-json.adoc[] +===== +====== + See xref:manual/json-template-layout.adoc[JSON Template Layout] page for the complete documentation. [id=pattern-layout] @@ -1727,7 +1756,7 @@ If the Marker in the log event is equal to or is an ancestor of the name specifi ==== ScriptPatternSelector The ScriptPatternSelector executes a script as described in the -xref:manual/configuration.adoc#Scripts[Scripts] section of the Configuration chapter. +xref:manual/scripts.adoc[Scripts] section of the Configuration chapter. The script is passed all the properties configured in the Properties section of the configuration, the StrSubstitutor used by the Configuration in the "substitutor" variables, and the log event in the "logEvent" variable, and is expected to return the value of the PatternMatch key that should be used, or null if the default pattern should be used. [source,xml] @@ -1939,7 +1968,8 @@ To get the most out of it, mind the following checklist: * Enable xref:manual/garbagefree.adoc[garbage-free logging] * Mind xref:#PatternLayout-gcfree[the garbage footprint of features you use] -* Don't give too much slack to xref:manual/configuration.adoc#log4j2.layoutStringBuilderMaxSize[`log4j2.layoutStringBuilderMaxSize`] and try to keep it relatively tight +* Don't give too much slack to xref:manual/systemproperties.adoc#log4j2.layoutStringBuilderMaxSize[`log4j2 +.layoutStringBuilderMaxSize`] and try to keep it relatively tight [#RFC5424Layout] == RFC5424 Layout @@ -2202,7 +2232,16 @@ To include any custom field in the output, use the following syntax: Custom fields are always last, in the order they are declared. The values support xref:manual/lookups.adoc[lookups]. -NOTE: Additional xref:runtime-dependencies.adoc[runtime dependencies] are required for using XmlLayout. +[NOTE] +====== +Additional runtime dependencies are required for using `XmlLayout`: + +.Runtime dependencies +[%collapsible,id=log4j-layout-xml-deps] +===== +include::partial$manual/dependencies-log4j-layout-xml.adoc[] +===== +====== [[YamlLayout]] == YAML Layout @@ -2279,4 +2318,13 @@ To include any custom field in the output, use the following syntax: Custom fields are always last, in the order they are declared. The values support xref:manual/lookups.adoc[lookups]. -NOTE: Additional xref:runtime-dependencies.adoc[runtime dependencies] are required for using YamlLayout. +[NOTE] +====== +Additional runtime dependencies are required for using `YamlLayout`: + +.Runtime dependencies +[%collapsible,id=log4j-layout-yaml-deps] +===== +include::partial$manual/dependencies-log4j-layout-yaml.adoc[] +===== +====== diff --git a/src/site/antora/modules/ROOT/pages/manual/logsep.adoc b/src/site/antora/modules/ROOT/pages/manual/logsep.adoc index c2a12d4c0f..e277989943 100644 --- a/src/site/antora/modules/ROOT/pages/manual/logsep.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/logsep.adoc @@ -108,7 +108,8 @@ in each web application. The `JndiContextSelector` will not work unless `log4j2.enableJndi=true` is set as a system property or environment variable. See the -xref:manual/configuration.adoc#enableJndi[log4j2.enableJndi] system property. +xref:manual/systemproperties.adoc#log4j2.enableJndiContextSelector[log4j2.enableJndiContextSelector] +configuration property. The exact method for setting system properties depends on the container. For Tomcat, edit `$CATALINA_HOME/conf/catalina.properties`. Consult the diff --git a/src/site/antora/modules/ROOT/pages/manual/lookups.adoc b/src/site/antora/modules/ROOT/pages/manual/lookups.adoc index 1ba41d110b..6eea0d2afe 100644 --- a/src/site/antora/modules/ROOT/pages/manual/lookups.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/lookups.adoc @@ -269,7 +269,7 @@ For example: As of Log4j 2.15.1 JNDI operations require that `log4j2.enableJndi=true` be set as a system property or the corresponding environment variable for this lookup to function. See the -xref:manual/configuration.adoc#enableJndiLookup[log4j2.enableJndiLookup] system property. +xref:manual/systemproperties.adoc#log4j2.enableJndiLookup[log4j2.enableJndiLookup] system property. The JndiLookup allows variables to be retrieved via JNDI. By default the key will be prefixed with java:comp/env/, however if the key contains a diff --git a/src/site/antora/modules/ROOT/pages/manual/messages.adoc b/src/site/antora/modules/ROOT/pages/manual/messages.adoc index 742e1e286e..7327330755 100644 --- a/src/site/antora/modules/ROOT/pages/manual/messages.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/messages.adoc @@ -57,8 +57,8 @@ https://docs.oracle.com/javase/{/docs/api/java/lang/Throwable.html[`Throwable`] `log.logger`:: The xref:manual/api.adoc#logger-names[logger name] provided explicitly to `LogManager.getLogger()` or inferred by Log4j API. <2> Contextual fields: -`tags`:: The stack of xref:manual/thread-context.adoc#nested-diagnostic-context[nested diagnostic context] messages. -`labels`:: The key/value pairs of the current xref:manual/thread-context.adoc#mapped-diagnostic-context[mapped diagnostic context]. +`tags`:: The stack of xref:manual/thread-context.adoc#usage[nested diagnostic context] messages. +`labels`:: The key/value pairs of the current xref:manual/thread-context.adoc#usage[mapped diagnostic context]. <3> Logging backend specific fields. In case you are using Log4j Core, the following fields can be automatically generated: @@ -176,7 +176,7 @@ Some appenders convert the `MapMessage` objects differently when there is no lay * JMS Appender converts to a JMS `javax.jms.MapMessage`. * xref:manual/appenders.adoc#JDBCAppender[JDBC Appender] converts to values in an `SQL INSERT` statement -* xref:manual/appenders.adoc#NoSQLAppenderMongoDBMain[MongoDB Appender] converts to fields in MongoDB object +* xref:manual/appenders.adoc#NoSQLAppenderMongoDB[MongoDB NoSQL provider] converts to fields in MongoDB object [#MessageFormatMessage] === `MessageFormatMessage` diff --git a/src/site/antora/modules/ROOT/pages/manual/status-logger.adoc b/src/site/antora/modules/ROOT/pages/manual/status-logger.adoc index 28c476f068..27cbdc1c6d 100644 --- a/src/site/antora/modules/ROOT/pages/manual/status-logger.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/status-logger.adoc @@ -69,7 +69,8 @@ Due to several complexities involved, **you are strongly advised to xref:#proper . Providing properties in a `{status-logger-properties-file-name}` file in the classpath . Using Log4j configuration (i.e., `<Configuration status="WARN" dest="out">` in a `log4j2.xml` in the classpath) + -WARNING: Since version `2.24.0`, `status` attribute in the `Configuration` element is deprecated and should be replaced with the xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] configuration property. +WARNING: Since version `2.24.0`, `status` attribute in the `Configuration` element is deprecated and should be +replaced with the <<log4j2.statusLoggerLevel>> configuration property. . Programmatically (e.g., `StatusLogger.getLogger().setLevel(Level.WARN)`) It is crucial to understand that there is a time between the first `StatusLogger` access and a configuration file (e.g., `log4j2.xml`) read. diff --git a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-1.2-api.adoc similarity index 56% copy from src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc copy to src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-1.2-api.adoc index 9bc18d982d..349feafc4c 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc +++ b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-1.2-api.adoc @@ -1,5 +1,5 @@ //// -Licensed to the Apache Software Foundation (ASF) under one or more + 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 @@ -15,14 +15,24 @@ Licensed to the Apache Software Foundation (ASF) under one or more limitations under the License. //// -// TODO: turn this into a velocity template for all the version numbers -= Web Servlet Containers +[tabs] +==== +Maven:: ++ +[source,xml,subs="+attributes"] +---- +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-1.2-api</artifactId> + <version>{log4j-core-version}</version> + <scope>runtime</scope> +</dependency> +---- -The Web module provides support for automatically enabling Log4j in Servlet containers. - -See the user manual page on xref:manual/webapp.adoc[Web Applications and JSPs] for details on using Log4j 2 in Web Applications. - -== Requirements - -The Web module requires Servlet 5.0 at minimum and is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. +Gradle:: ++ +[source,groovy,subs="+attributes"] +---- +runtimeOnly 'org.apache.logging.log4j:log4j-1.2-api:{log4j-core-version}' +---- +==== \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-csv.adoc similarity index 56% copy from src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc copy to src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-csv.adoc index 9bc18d982d..38b130a52d 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc +++ b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-csv.adoc @@ -1,5 +1,5 @@ //// -Licensed to the Apache Software Foundation (ASF) under one or more + 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 @@ -15,14 +15,24 @@ Licensed to the Apache Software Foundation (ASF) under one or more limitations under the License. //// -// TODO: turn this into a velocity template for all the version numbers -= Web Servlet Containers +[tabs] +==== +Maven:: ++ +[source,xml,subs="+attributes"] +---- +<dependency> + <groupId>org.apache.commons</groupId> + <artifactId>commons-csv</artifactId> + <version>{commons-csv-version}</version> + <scope>runtime</scope> +</dependency> +---- -The Web module provides support for automatically enabling Log4j in Servlet containers. - -See the user manual page on xref:manual/webapp.adoc[Web Applications and JSPs] for details on using Log4j 2 in Web Applications. - -== Requirements - -The Web module requires Servlet 5.0 at minimum and is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. +Gradle:: ++ +[source,groovy,subs="+attributes"] +---- +runtimeOnly 'org.apache.commons:commons-csv:{commons-csv-version}' +---- +==== \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-json.adoc similarity index 56% copy from src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc copy to src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-json.adoc index 9bc18d982d..cbda221184 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc +++ b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-json.adoc @@ -1,5 +1,5 @@ //// -Licensed to the Apache Software Foundation (ASF) under one or more + 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 @@ -15,14 +15,24 @@ Licensed to the Apache Software Foundation (ASF) under one or more limitations under the License. //// -// TODO: turn this into a velocity template for all the version numbers -= Web Servlet Containers +[tabs] +==== +Maven:: ++ +[source,xml,subs="+attributes"] +---- +<dependency> + <groupId>com.fasterxml.jackson.core</groupId> + <artifactId>jackson-databind</artifactId> + <version>{jackson-version}</version> + <scope>runtime</scope> +</dependency> +---- -The Web module provides support for automatically enabling Log4j in Servlet containers. - -See the user manual page on xref:manual/webapp.adoc[Web Applications and JSPs] for details on using Log4j 2 in Web Applications. - -== Requirements - -The Web module requires Servlet 5.0 at minimum and is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. +Gradle:: ++ +[source,groovy,subs="+attributes"] +---- +runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:{jackson-version}' +---- +==== \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/log4j-web.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-template-json.adoc similarity index 56% copy from src/site/antora/modules/ROOT/pages/log4j-web.adoc copy to src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-template-json.adoc index ef365413ea..644d2c5115 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-web.adoc +++ b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-template-json.adoc @@ -1,5 +1,5 @@ //// -Licensed to the Apache Software Foundation (ASF) under one or more + 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 @@ -15,14 +15,24 @@ Licensed to the Apache Software Foundation (ASF) under one or more limitations under the License. //// -// TODO: turn this into a velocity template for all the version numbers -= Web Servlet Containers +[tabs] +==== +Maven:: ++ +[source,xml,subs="+attributes"] +---- +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-layout-template-json</artifactId> + <version>{log4j-layout-template-json-version}</version> + <scope>runtime</scope> +</dependency> +---- -The Web module provides support for automatically enabling Log4j in Servlet containers. - -See the user manual page on xref:manual/webapp.adoc[Web Applications and JSPs] for details on using Log4j 2 in Web Applications. - -== Requirements - -The Web module requires Servlet 2.5 at minimum and is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. +Gradle:: ++ +[source,groovy,subs="+attributes"] +---- +runtimeOnly 'org.apache.logging.log4j:log4j-layout-template-json:{log4j-layout-template-json-version}' +---- +==== \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-xml.adoc similarity index 56% copy from src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc copy to src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-xml.adoc index 9bc18d982d..50007bccfb 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc +++ b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-xml.adoc @@ -1,5 +1,5 @@ //// -Licensed to the Apache Software Foundation (ASF) under one or more + 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 @@ -15,14 +15,24 @@ Licensed to the Apache Software Foundation (ASF) under one or more limitations under the License. //// -// TODO: turn this into a velocity template for all the version numbers -= Web Servlet Containers +[tabs] +==== +Maven:: ++ +[source,xml,subs="+attributes"] +---- +<dependency> + <groupId>com.fasterxml.jackson.dataformat</groupId> + <artifactId>jackson-dataformat-xml</artifactId> + <version>{jackson-version}</version> + <scope>runtime</scope> +</dependency> +---- -The Web module provides support for automatically enabling Log4j in Servlet containers. - -See the user manual page on xref:manual/webapp.adoc[Web Applications and JSPs] for details on using Log4j 2 in Web Applications. - -== Requirements - -The Web module requires Servlet 5.0 at minimum and is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. +Gradle:: ++ +[source,groovy,subs="+attributes"] +---- +runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-xml:{jackson-version}' +---- +==== \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-yaml.adoc similarity index 56% copy from src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc copy to src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-yaml.adoc index 9bc18d982d..1459a1a9b2 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-jakarta-web.adoc +++ b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-yaml.adoc @@ -1,5 +1,5 @@ //// -Licensed to the Apache Software Foundation (ASF) under one or more + 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 @@ -15,14 +15,24 @@ Licensed to the Apache Software Foundation (ASF) under one or more limitations under the License. //// -// TODO: turn this into a velocity template for all the version numbers -= Web Servlet Containers +[tabs] +==== +Maven:: ++ +[source,xml,subs="+attributes"] +---- +<dependency> + <groupId>com.fasterxml.jackson.dataformat</groupId> + <artifactId>jackson-dataformat-yaml</artifactId> + <version>{jackson-version}</version> + <scope>runtime</scope> +</dependency> +---- -The Web module provides support for automatically enabling Log4j in Servlet containers. - -See the user manual page on xref:manual/webapp.adoc[Web Applications and JSPs] for details on using Log4j 2 in Web Applications. - -== Requirements - -The Web module requires Servlet 5.0 at minimum and is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. +Gradle:: ++ +[source,groovy,subs="+attributes"] +---- +runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:{jackson-version}' +---- +==== \ No newline at end of file
