You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by vy...@apache.org on 2024/03/22 08:52:47 UTC
(logging-log4j2) branch 2.x-docgen-antora updated: Initial Antora migration
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x-docgen-antora
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x-docgen-antora by this push:
new ccf648b995 Initial Antora migration
ccf648b995 is described below
commit ccf648b995b7a566680689741c5f265631eb724d
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Fri Mar 22 09:52:30 2024 +0100
Initial Antora migration
---
pom.xml | 34 ++-
src/asciidoc-templates/document.html.erb | 184 +++++++++++++++++
src/docgen-templates/index.adoc.ftl | 13 +-
src/docgen-templates/license.adoc | 16 --
src/docgen-templates/type.adoc.ftl | 29 +--
src/site/antora/modules/ROOT/nav.adoc | 34 ++-
src/site/antora/modules/ROOT/pages/components.adoc | 45 ----
src/site/antora/modules/ROOT/pages/docs.adoc | 228 ---------------------
src/site/antora/modules/ROOT/pages/download.adoc | 2 -
.../antora/modules/ROOT/pages/log4j-docker.adoc | 10 +-
.../antora/modules/ROOT/pages/log4j-flume-ng.adoc | 12 +-
src/site/antora/modules/ROOT/pages/log4j-jul.adoc | 9 +-
.../modules/ROOT/pages/log4j-kubernetes.adoc | 12 +-
.../antora/modules/ROOT/pages/log4j-mongodb4.adoc | 8 +-
.../pages/manual}/api-separation.adoc | 0
.../{manual/pages => ROOT/pages/manual}/api.adoc | 0
.../pages => ROOT/pages/manual}/appenders.adoc | 0
.../pages => ROOT/pages/manual}/architecture.adoc | 0
.../{manual/pages => ROOT/pages/manual}/async.adoc | 0
.../{manual/pages => ROOT/pages/manual}/cloud.adoc | 0
.../pages => ROOT/pages/manual}/compatibility.adoc | 0
.../pages => ROOT/pages/manual}/configuration.adoc | 0
.../pages => ROOT/pages/manual}/customconfig.adoc | 0
.../pages/manual}/customloglevels.adoc | 0
.../pages => ROOT/pages/manual}/eventlogging.adoc | 0
.../pages => ROOT/pages/manual}/extending.adoc | 0
.../pages => ROOT/pages/manual}/filters.adoc | 0
.../pages => ROOT/pages/manual}/flowtracing.adoc | 0
.../pages => ROOT/pages/manual}/garbagefree.adoc | 0
.../antora/modules/ROOT/pages/manual/index.adoc | 210 +++++++++++++++++++
.../{manual/pages => ROOT/pages/manual}/jmx.adoc | 0
.../pages/manual}/json-template-layout.adoc | 2 -
.../pages => ROOT/pages/manual}/layouts.adoc | 0
.../pages => ROOT/pages/manual}/logbuilder.adoc | 0
.../pages => ROOT/pages/manual}/logsep.adoc | 0
.../pages => ROOT/pages/manual}/lookups.adoc | 0
.../pages => ROOT/pages/manual}/markers.adoc | 0
.../pages => ROOT/pages/manual}/messages.adoc | 0
.../pages => ROOT/pages/manual}/migration.adoc | 0
.../pages => ROOT/pages/manual}/plugins.adoc | 10 +-
.../pages/manual}/thread-context.adoc | 0
.../{manual/pages => ROOT/pages/manual}/usage.adoc | 0
.../pages => ROOT/pages/manual}/webapp.adoc | 0
src/site/antora/modules/manual/pages/index.adoc | 138 -------------
44 files changed, 486 insertions(+), 510 deletions(-)
diff --git a/pom.xml b/pom.xml
index 68f1b8fc62..878aca4c86 100644
--- a/pom.xml
+++ b/pom.xml
@@ -676,6 +676,7 @@
<goal>export</goal>
</goals>
<phase>pre-site</phase>
+ <inherited>false</inherited>
<configuration>
<outputDirectory>${project.build.directory}/generated-site/antora/modules/ROOT/pages</outputDirectory>
<indexTemplates>
@@ -756,9 +757,6 @@
<resource>
<directory>${project.basedir}/src/site</directory>
<excludes>
- <exclude>/_release-notes/*</exclude>
- <exclude>/_release-notes.adoc</exclude>
- <exclude>/_constants.*</exclude>
<exclude>/resources/logo/**/*</exclude>
</excludes>
</resource>
@@ -846,12 +844,11 @@
<templateDirectory>${project.basedir}/src/docgen-templates</templateDirectory>
<indexTemplate>
<source>index.adoc.ftl</source>
- <target>${project.build.directory}/generated-site/asciidoc/plugin-reference/index.adoc</target>
+ <target>${project.build.directory}/generated-site/asciidoc/plugin-reference.adoc</target>
</indexTemplate>
<typeTemplate>
<source>type.adoc.ftl</source>
- <!-- `target` must be in sync. with the `log4j-docgen-type-template-target` configuration of `log4j-docgen-asciidoctor-extension`! -->
- <target>${project.build.directory}/generated-site/asciidoc/plugin-reference/%g/%a/%c.adoc</target>
+ <target>${project.build.directory}/generated-site/asciidoc/_plugin-reference/%g-%a-%c.adoc</target>
</typeTemplate>
</configuration>
</execution>
@@ -908,6 +905,7 @@
</executions>
</plugin>
+ <!-- Run Antora -->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
@@ -925,7 +923,7 @@
<arguments>
<argument>${project.basedir}/node_modules/.bin/antora</argument>
<argument>${project.basedir}/antora-playbook.yml</argument>
- <argument>--to-dir=${project.build.directory}/antora-site</argument>
+ <argument>--to-dir=${project.build.directory}/site</argument>
</arguments>
</configuration>
</execution>
@@ -964,6 +962,8 @@
</dependencies>
<executions>
+
+ <!-- Skip the `export-asciidoc-to-html` execution inherited from `logging-parent` -->
<execution>
<!-- Execution ID must match the one inherited from `logging-parent` (i.e., `export-asciidoc-to-html`) to override it! -->
<id>export-asciidoc-to-html</id>
@@ -973,6 +973,20 @@
<phase>site</phase>
<configuration combine.self="override">
<skip>true</skip>
+ </configuration>
+ </execution>
+
+ <!-- Docgen AsciiDoc files cannot be compiled using Antora.
+ Docgen-generated AsciiDoc contains `apiref` macro and `log4j-docgen-antra-extension` resolving it is a Java library.
+ Antora is written in JavaScript and cannot run Java extensions.
+ Hence, we use `asciidoctor-maven-plugin` to compile Docgen AsciiDoc files. -->
+ <execution>
+ <id>export-docgen-asciidoc-to-html</id>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <phase>site</phase>
+ <configuration combine.self="override">
<resources>
<resource>
<directory>${project.build.directory}/generated-site/resources</directory>
@@ -980,7 +994,7 @@
</resources>
<sourceDirectory>${project.build.directory}/generated-site/asciidoc</sourceDirectory>
<outputDirectory>${project.build.directory}/site</outputDirectory>
- <preserveDirectories>true</preserveDirectories>
+ <preserveDirectories>false</preserveDirectories>
<templateDirs>
<dir>${project.basedir}/src/asciidoc-templates</dir>
</templateDirs>
@@ -989,11 +1003,11 @@
<toc>left</toc>
<log4j-docgen-descriptor-directory>${project.build.directory}/plugin-descriptors</log4j-docgen-descriptor-directory>
<log4j-docgen-type-filter-exclude-pattern>${log4j.docgen.typeFilter.excludePattern}</log4j-docgen-type-filter-exclude-pattern>
- <!-- `log4j-docgen-type-template-target` must be in sync. with the `typeTemplate` configuration of `log4j-docgen-maven-plugin`! -->
- <log4j-docgen-type-template-target>../../%g/%a/%c.html</log4j-docgen-type-template-target>
+ <log4j-docgen-type-target-template><![CDATA[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${sourcedType.type.className?replace('.', '-')}]]></log4j-docgen-type-target-template>
</attributes>
</configuration>
</execution>
+
</executions>
</plugin>
diff --git a/src/asciidoc-templates/document.html.erb b/src/asciidoc-templates/document.html.erb
new file mode 100644
index 0000000000..501944d358
--- /dev/null
+++ b/src/asciidoc-templates/document.html.erb
@@ -0,0 +1,184 @@
+<%#
+ 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.
+%>
+<%#
+ Code is based on an example found in this repository:
+ https://github.com/asciidoctor/asciidoctor-backends/blob/master/erb/html5/document.html.erb
+%>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <meta name="generator" content="Asciidoctor <%= attr 'asciidoctor-version' %>">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <%
+ [:description, :keywords, :author, :copyright].each do |key|
+ if attr? key %>
+ <meta name="<%= key %>" content="<%= attr key %>"><%
+ end
+ end
+ %>
+ <title><%= doctitle(:sanitize => true) || (attr 'untitled-label') %></title>
+
+ <link rel="stylesheet" href="font-awesome-4.7.0/css/font-awesome.min.css">
+ <link rel="stylesheet" href="css/fonts.css">
+ <%= Asciidoctor::Stylesheets.instance.embed_primary_stylesheet %>
+ <link rel="stylesheet" href="css/logging-custom.css">
+
+ <!-- Code Highlighter -->
+ <%= syntax_highlighter&.docinfo :head, self, {} %>
+ <%= (docinfo_content = docinfo).empty? ? nil : %(#{docinfo_content}) %>
+
+</head>
+<body>
+
+<div id="header">
+ <div class="logo">
+ <a href="index.html"><img src="images/log4j-logo.png" alt="Apache Log4j Logo"/></a>
+ </div>
+
+ <div class="menu-mobile">
+ <i class="fa fa-bars" aria-hidden="true"></i>
+ </div>
+
+ <div class="navs">
+ <div class="menu-mobile-close">
+ <i class="fa fa-window-close" aria-hidden="true"></i>
+ </div>
+ <nav class="main-menu" aria-label="Main Navigation">
+ <ul>
+ <li><a href="index.html">Home</a></li>
+ </ul>
+ </nav>
+ </div>
+</div>
+
+<div class="content-container">
+ <%
+ if (attr? :toc) && (attr? 'toc-placement', 'auto') %>
+ <div class="table-of-content">
+
+ <div class="table-of-content-title" id="toctitle"><%= attr 'toc-title' %></div>
+ <%= converter.convert self, 'outline' %>
+ </div><%
+ end
+ %>
+
+ <div id="content">
+ <h1><%= doctitle %></h1>
+ <%= content %>
+ </div><%
+ unless !footnotes? || attr?(:nofootnotes) %>
+ <div id="footnotes">
+ <hr><%
+ footnotes.each do |fn| %>
+ <div class="footnote" id="_footnote_<%= fn.index %>">
+ <a href="#_footnoteref_<%= fn.index %>"><%= fn.index %></a>. <%= fn.text %>
+ </div><%
+ end %>
+ </div><%
+ end %>
+</div>
+<% unless nofooter %>
+ <div id="footer">
+ <div class="footer-text">
+ <div>
+ <%
+ if attr? :revnumber %>
+ <%= %(#{attr 'version-label'} #{attr :revnumber}) %><br><%
+ end
+ if attr? 'last-update-label' %>
+ <%= %(#{attr 'last-update-label'} #{attr :docdatetime}) %><%
+ end %><%= (docinfo_content = (docinfo :footer)).empty? ? nil : %(
+ #{docinfo_content}) %>
+ </div>
+ <div>
+ Copyright © 2017-2024 <a href="http://www.apache.org">The Apache Software Foundation</a>. Licensed under the Apache Software License, Version 2.0 Please read our <a href="https://privacy.apache.org/policies/privacy-policy-public.html">privacy policy</a>.
+ <br/>
+ Apache, Chainsaw, log4cxx, Log4j, Log4net, log4php, Flume and the Apache feather logo are trademarks or registered trademarks of The Apache Software Foundation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
+ </div>
+ </div>
+ </div><%
+ end %>
+
+<script>
+ document.addEventListener('DOMContentLoaded', function() {
+ const header = document.querySelector('#header');
+ const toc = document.querySelector('.table-of-content');
+
+ window.addEventListener('scroll', function() {
+ const headerRect = header.getBoundingClientRect();
+ const rect = toc.getBoundingClientRect();
+
+ if (headerRect.bottom >= 0) {
+ toc.classList.remove('sticky-effect');
+ toc.classList.remove('sticky');
+ } else if (rect.top <= 0) {
+ toc.classList.add('sticky');
+ toc.classList.add('sticky-effect');
+ }
+
+ });
+ });
+</script>
+<script>
+ document.addEventListener('DOMContentLoaded', function () {
+ var menuIcon = document.querySelector('.menu-mobile');
+ var menuIconClose = document.querySelector('.menu-mobile-close');
+ var menu = document.querySelector('.navs');
+
+ var duration = 0.7;
+ menuIcon.addEventListener('click', function () {
+ if (menu.classList.contains('menu-open')) {
+ menu.classList.remove('menu-open');
+ } else {
+ menu.classList.add('menu-open');
+ }
+ });
+
+ menuIconClose.addEventListener('click', function () {
+ if (menu.classList.contains('menu-open')) {
+ menu.classList.remove('menu-open');
+ }
+ });
+ });
+</script>
+<script>
+ document.addEventListener('DOMContentLoaded', function() {
+ var menuItems = document.querySelectorAll('#header nav > ul > li');
+
+ for (var i = 0; i < menuItems.length; i++) {
+ menuItems[i].addEventListener('click', function(event) {
+ // check if the sub menu was clicked
+ if (event.target.closest('.menu-drop-down')) {
+ return;
+ }
+
+ var subMenu = this.getElementsByClassName('menu-drop-down')[0];
+ if (subMenu.style.display === 'flex') {
+ subMenu.style.display = 'none';
+ } else {
+ subMenu.style.display = 'flex';
+ }
+
+ // Prevent navigating to '#' link on parent menu item
+ event.preventDefault();
+ });
+ }
+ });
+</script>
+</body>
+</html>
diff --git a/src/docgen-templates/index.adoc.ftl b/src/docgen-templates/index.adoc.ftl
index 48e8d0fd3b..9dc1d8c733 100644
--- a/src/docgen-templates/index.adoc.ftl
+++ b/src/docgen-templates/index.adoc.ftl
@@ -16,7 +16,6 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
<#-- @ftlvariable name="lookup" type="org.apache.logging.log4j.docgen.generator.TypeLookup" -->
-<#include "license.adoc">
= Plugin reference
@@ -33,10 +32,10 @@ This not only allows Log4j itself to be developed in individual components, but
[#shortcuts]
== Shortcuts
-* xref:org.apache.logging.log4j/log4j-core/org.apache.logging.log4j.core.config.Configuration.adoc[The `<Configuration>` element assembly in a `log4j2.xml`]
-* xref:org.apache.logging.log4j/log4j-core/org.apache.logging.log4j.core.Appender.adoc[The type hierarchy of *appenders*]
-* xref:org.apache.logging.log4j/log4j-core/org.apache.logging.log4j.core.Layout.adoc[The type hierarchy of *layouts*]
-* xref:org.apache.logging.log4j/log4j-core/org.apache.logging.log4j.core.Filter.adoc[The type hierarchy of *filters*]
+* xref:#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Configuration[The `<Configuration>` element assembly in a `log4j2.xml`]
+* xref:#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Appender[The type hierarchy of *appenders*]
+* xref:#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Layout[The type hierarchy of *layouts*]
+* xref:#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Filter[The type hierarchy of *filters*]
[#index]
== Index
@@ -52,9 +51,9 @@ Below is a list of all types reachable by plugins grouped by the Maven coordinat
<#assign lastGroupId = sourcedType.groupId/>
<#assign lastArtifactId = sourcedType.artifactId/>
-[#${sourcedType.groupId?replace('.', '_')}-${sourcedType.artifactId?replace('.', '_')}]
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}]
=== `${sourcedType.groupId}:${sourcedType.artifactId}`
</#if>
-* xref:${sourcedType.groupId}/${sourcedType.artifactId}/${sourcedType.type.className}.adoc[`${sourcedType.type.className}`]
+include::_plugin-reference/${sourcedType.groupId}-${sourcedType.artifactId}-${sourcedType.type.className}.adoc[leveloffset=+4]
</#list>
diff --git a/src/docgen-templates/license.adoc b/src/docgen-templates/license.adoc
deleted file mode 100644
index 797f7c9fb7..0000000000
--- a/src/docgen-templates/license.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-////
-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
-
- https://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.
-////
diff --git a/src/docgen-templates/type.adoc.ftl b/src/docgen-templates/type.adoc.ftl
index 3c087e7a96..48f8dc2478 100644
--- a/src/docgen-templates/type.adoc.ftl
+++ b/src/docgen-templates/type.adoc.ftl
@@ -19,23 +19,19 @@
<#assign type = sourcedType.type/>
<#-- @ftlvariable name="type" type="org.apache.logging.log4j.docgen.Type" -->
<#-- @ftlvariable name="lookup" type="org.apache.logging.log4j.docgen.generator.TypeLookup" -->
-<#include "license.adoc">
-[#${type.className?replace('.', '_')}]
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}]
= ${type.name!('`' + type.className + '`')}
Class:: `${type.className}`
-<#if sourcedType.groupId?has_content && sourcedType.artifactId?has_content>
Provider:: `${sourcedType.groupId}:${sourcedType.artifactId}`
-</#if>
-
${(type.description.text)!}
<#assign hasElements = ((type.elements?size)!0) != 0/>
<#if type.class.simpleName == 'PluginType'>
<#-- @ftlvariable name="type" type="org.apache.logging.log4j.docgen.PluginType" -->
-[#${type.className?replace('.', '_')}-XML-snippet]
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}_XML-snippet]
== XML snippet
[source, xml]
----
@@ -71,7 +67,7 @@ ${indent}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(hasElements?the
</#if>
<#if type.attributes?has_content>
-[#${type.className?replace('.', '_')}-attributes]
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}-attributes]
== Attributes
Optional attributes are denoted by `?`-suffixed types.
@@ -86,7 +82,7 @@ Optional attributes are denoted by `?`-suffixed types.
<#assign attrTypeName = attr.type?contains('.')?then(attr.type?keep_after_last('.'), attr.type)/>
<#if lookup[attr.type]??>
<#assign attrSourcedType = lookup[attr.type]/>
-|xref:../../${attrSourcedType.groupId}/${attrSourcedType.artifactId}/${attr.type}.adoc[${attrTypeName}]${requirementSuffix}
+|xref:#${attrSourcedType.groupId?replace('.', '-')}_${attrSourcedType.artifactId?replace('.', '-')}_${attr.type?replace('.', '-')}[${attrTypeName}]${requirementSuffix}
<#else>
|${attrTypeName}${requirementSuffix}
</#if>
@@ -98,7 +94,7 @@ a|${(attr.description.text)!}
</#if>
<#if hasElements>
-[#${type.className?replace('.', '_')}-components]
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}_components]
== Nested components
Optional components are denoted by `?`-suffixed types.
@@ -115,7 +111,7 @@ Optional components are denoted by `?`-suffixed types.
<#assign elementSourcedType = lookup[element.type]/>
<#assign tagCell = elementSourcedType.type.name!/>
|${tagCell}
-|xref:../../${elementSourcedType.groupId}/${elementSourcedType.artifactId}/${element.type}.adoc[${elementName}]${requirementSuffix}
+|xref:#${elementSourcedType.groupId?replace('.', '-')}_${elementSourcedType.artifactId?replace('.', '-')}_${element.type?replace('.', '-')}[${elementName}]${requirementSuffix}
<#else>
|
|${elementName}${requirementSuffix}
@@ -127,20 +123,11 @@ a|${descriptionCell}
</#if>
<#if type.implementations?has_content>
-[#${type.className?replace('.', '_')}-implementations]
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}_implementations]
== Known implementations
<#list type.implementations as impl>
<#assign implSourcedType = lookup[impl]/>
-* xref:../../${implSourcedType.groupId}/${implSourcedType.artifactId}/${impl}.adoc[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}]
+* xref:#${implSourcedType.groupId?replace('.', '-')}_${implSourcedType.artifactId?replace('.', '-')}_${impl?replace('.', '-')}[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}]
</#list>
</#if>
-
-[#shortcuts]
-== Shortcuts
-
-* xref:../../index.adoc[The plugin reference]
-* xref:../../org.apache.logging.log4j/log4j-core/org.apache.logging.log4j.core.config.Configuration.adoc[The `<Configuration>` element assembly in a `log4j2.xml`]
-* xref:../../org.apache.logging.log4j/log4j-core/org.apache.logging.log4j.core.Appender.adoc[The type hierarchy of *appenders*]
-* xref:../../org.apache.logging.log4j/log4j-core/org.apache.logging.log4j.core.Layout.adoc[The type hierarchy of *layouts*]
-* xref:../../org.apache.logging.log4j/log4j-core/org.apache.logging.log4j.core.Filter.adoc[The type hierarchy of *filters*]
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
index 4a89e2bb49..c742af1058 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -14,5 +14,37 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-* xref:index.adoc[]
+
+* Learn
+** xref:manual/index.adoc[Manual]
+** link:plugin-reference.html[Plugins reference]
+** xref:javadoc.adoc[Java API reference]
+** xref:articles.adoc[Articles]
+** xref:faq.adoc[F.A.Q.]
+* Get
+** xref:download.adoc[Download]
+** xref:runtime-dependencies.adoc[]
* xref:support.adoc[]
+** xref:security.adoc[]
+** xref:thanks.adoc[Thanks]
+* Components
+** Internal components
+*** xref:log4j-api.adoc[]
+*** xref:log4j-1.2-api.adoc[]
+*** xref:log4j-slf4j-impl.adoc[]
+*** xref:log4j-jul.adoc[]
+*** xref:log4j-jpl.adoc[]
+*** xref:log4j-to-slf4j.adoc[]
+*** xref:log4j-flume-ng.adoc[]
+*** xref:log4j-mongodb4.adoc[]
+*** xref:log4j-iostreams.adoc[]
+*** xref:log4j-docker.adoc[]
+*** xref:log4j-kubernetes.adoc[]
+*** xref:log4j-spring-cloud-config-client.adoc[]
+** External components
+*** link:/log4j/jakarta[Log4j Jakarta EE]
+*** link:/log4j/jmx-gui[Log4j JMX GUI]
+*** link:/log4j/kotlin[Log4j Kotlin]
+*** link:/log4j/scala[Log4j Scala]
+*** link:/log4j/tools[Log4j Tools]
+*** link:/log4j/transform[Log4j Transformation Tools]
diff --git a/src/site/antora/modules/ROOT/pages/components.adoc b/src/site/antora/modules/ROOT/pages/components.adoc
deleted file mode 100644
index b199f56701..0000000000
--- a/src/site/antora/modules/ROOT/pages/components.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-////
- 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.
-////
-= Components of Apache Log4j
-
-== Internal Components
-
-* xref:/log4j-api.html[API]
-* xref:/log4j-core.html[Implementation]
-* xref:/log4j-1.2-api.html[Log4j 1.2 API]
-* xref:/log4j-slf4j-impl.html[SLF4J Binding]
-* xref:/log4j-jul.html[JUL Adapter]
-* xref:/log4j-jpl.html[JDK Platform Logger]
-* xref:/log4j-to-slf4j.html[Log4j 2 to SLF4J Adapter]
-* xref:/log4j-jdbc-dbcp2.html[JDBC Appender]
-* xref:/log4j-flume-ng.html[Apache Flume Appender]
-* xref:/log4j-mongodb4.html[MongoDB 4 appender]
-* xref:/log4j-iostreams.html[IO Streams]
-* xref:/log4j-docker.html[Docker Support]
-* xref:/log4j-kubernetes.html[Kubernetes Support]
-* xref:/log4j-spring-cloud-config-client.html[Spring Cloud Config Client]
-* xref:/log4j-transform[Log4j Transformation Tools]
-
-== External Components
-
-* xref:/log4j/jakarta[Log4j Jakarta EE]
-* xref:/log4j/jmx-gui[Log4j JMX GUI]
-* xref:/log4j/kotlin[Log4j Kotlin]
-* xref:/log4j/scala[Log4j Scala]
-* xref:/log4j/tools[Log4j Tools]
-* xref:/log4j/transform[Log4j Transformation Tools]
-
diff --git a/src/site/antora/modules/ROOT/pages/docs.adoc b/src/site/antora/modules/ROOT/pages/docs.adoc
deleted file mode 100644
index effdc6e128..0000000000
--- a/src/site/antora/modules/ROOT/pages/docs.adoc
+++ /dev/null
@@ -1,228 +0,0 @@
-////
- 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.
-////
-= Documentation
-
-* xref:/manual/index.html[Introduction]
-* xref:/manual/architecture.html[Architecture]
-* xref:/manual/migration.html[Log4j 1.x Migration]
-
-== Java API
-
-* xref:/manual/api.html[Java API]
-* xref:/manual/logbuilder.html[Log Builder]
-* xref:/manual/flowtracing.html[Flow Tracing]
-* xref:/manual/markers.html[Markers]
-* xref:/manual/eventlogging.html[Event Logging]
-* xref:/manual/messages.html[Messages]
-* xref:/manual/thread-context.html[ThreadContext]
-
-== Configuration
-
-* xref:/manual/configuration.html[Configuration]
-* xref:/manual/configuration.html#Architecture[Configuration Architecture]
-* xref:/manual/configuration.html#Arbiters[Arbiters]
-* xref:/manual/configuration.html#AutomaticConfiguration[Automatic Configuration]
-* xref:/manual/configuration.html#Additivity[Additivity]
-* xref:/manual/configuration.html#AutomaticReconfiguration[Automatic Reconfiguration]
-* xref:/manual/configuration.html#ChainsawSupport[Chainsaw Support]
-* xref:/manual/configuration.html#ConfigurationSyntax"[Configuration Syntax]
-* xref:/manual/configuration.html#XML[XML Syntax]
-* xref:/manual/configuration.html#JSON[JSON Syntax]
-* xref:/manual/configuration.html#YAML[YAML Syntax]
-* xref:/manual/configuration.html#Properties[Properties Syntax]
-* xref:/manual/configuration.html#Loggers[Configuring Loggers]
-* xref:/manual/configuration.html#Appenders[Configuring Appenders]
-* xref:/manual/configuration.html#Filters[Configuring Filters]
-* xref:/manual/configuration.html#PropertySubstitution[Property Substitution]
-* xref:/manual/configuration.html#RuntimeLookup[Lookup Variables]
-* xref:/manual/configuration.html#Scripts[Scripts]
-* xref:/manual/configuration.html#XInclude[XInclude]
-* xref:/manual/configuration.html#CompositeConfiguration[Composite Configurations]
-* xref:/manual/configuration.html#StatusMessages[Status Messages]
-* xref:/manual/configuration.html#UnitTestingInMaven[Unit Testing]
-* xref:/manual/systemProperties.html[System Properties]
-
-== Usage
-
-* xref:/manual/usage.html[Usage]
-* xref:/manual/usage.html?#StaticVsNonStatic[Static vs non-Static Loggers]
-* xref:/manual/usage.html?#LoggerVsClass[Logger Name vs Class Name]
-* xref:/manual/cloud.html[Logging in the Cloud]
-
-== Performance
-
-* xref:/performance.html[Performance]
-* xref:/performance.html#benchmarks[Benchmarks]
-* xref:/performance.html#loglibComparison[Logging Library Comparison]
-* xref:/performance.html#asyncLogging[Async Logging Comparison]
-* xref:/performance.html#asyncLoggingResponseTime[Async Logging Latency]
-* xref:/performance.html#asyncLoggingWithParams[Parameters]
-* xref:/performance.html#asyncLoggingWithLocation[Location]
-* xref:/performance.html#fileLoggingComparison[File Logging Comparison]
-* xref:/performance.html#filtering[Filtering Comparison]
-* xref:/performance.html#tradeoffs[Trade-offs]
-
-== Lookups
-
-* xref:/manual/lookups.html[Lookups]
-* xref:/manual/lookups.html#ContextMapLookup[Context Map]
-* xref:/manual/lookups.html#DateLookup[Date]
-* xref:/manual/lookups.html#DockerLookup[Docker]
-* xref:/manual/lookups.html#EnvironmentLookup[Environment]
-* xref:/manual/lookups.html#EventLookup[Event]
-* xref:/manual/lookups.html#JavaLookup[Java]
-* xref:/manual/lookups.html#JndiLookup[JNDI]
-* xref:/manual/lookups.html#JmxRuntimeInputArgumentsLookup[JVM Arguments]
-* xref:/manual/lookups.html#KubernetesLookup[Kubernetes]
-* xref:/manual/lookups.html#Log4jConfigLookup[Log4j Config]
-* xref:/manual/lookups.html#LowerLookup[Lower]
-* xref:/manual/lookups.html#AppMainArgsLookup[Main Arguments]
-* xref:/manual/lookups.html#MapLookup[Map]
-* xref:/manual/lookups.html#StructuredDataLookup[Structured Data]
-* xref:/manual/lookups.html#SystemPropertiesLookup[System Properties]
-* xref:/manual/lookups.html#UpperLookup[Upper]
-
-== Appender
-
-* xref:/manual/appenders.html[Appenders]
-* xref:/manual/appenders.html#AsyncAppender[Async]
-* xref:/manual/appenders.html#ConsoleAppender[Console]
-* xref:/manual/appenders.html#FailoverAppender[Failover]
-* xref:/manual/appenders.html#FileAppender[File]
-* xref:/manual/appenders.html#FlumeAppender[Flume]
-* xref:/manual/appenders.html#JDBCAppender[JDBC]
-* xref:/manual/appenders.html#HttpAppender[HTTP]
-* xref:/manual/appenders.html#MemoryMappedFileAppender[Memory Mapped File]
-* xref:/manual/appenders.html#NoSQLAppender[NoSQL]
-* xref:/manual/appenders.html#NoSQLAppenderMongoDB[NoSQL for MongoDB]
-* xref:/manual/appenders.html#OutputStreamAppender[Output Stream]
-* xref:/manual/appenders.html#RandomAccessFileAppender[Random Access File]
-* xref:/manual/appenders.html#RewriteAppender[Rewrite]
-* xref:/manual/appenders.html#RollingFileAppender[Rolling File]
-* xref:/manual/appenders.html#RollingRandomAccessFileAppender[Rolling Random Access File]
-* xref:/manual/appenders.html#RoutingAppender[Routing]
-* xref:/manual/appenders.html#ScriptAppenderSelector[ScriptAppenderSelector]
-* xref:/manual/appenders.html#SocketAppender[Socket]
-* xref:/manual/appenders.html#SSL[SSL]
-* xref:/manual/appenders.html#SyslogAppender[Syslog]
-
-== Layouts
-
-* xref:/manual/layouts.html[Layouts]
-* xref:/manual/layouts.html#CSVLayouts[CSV]
-* xref:/manual/layouts.html#HTMLLayout[HTML]
-* xref:/manual/json-template-layout.html[JSON Template]
-* xref:/manual/layouts.html#PatternLayout[Pattern]
-* xref:/manual/layouts.html#RFC5424Layout[RFC-5424]
-* xref:/manual/layouts.html#SerializedLayout[Serialized]
-* xref:/manual/layouts.html#SyslogLayout[Syslog]
-* xref:/manual/layouts.html#LocationInformation[Location Information]
-
-== Filters
-
-* xref:/manual/filters.html[Filters]
-* xref:/manual/filters.html#BurstFilter[Burst]
-* xref:/manual/filters.html#CompositeFilter[Composite Filter]
-* xref:/manual/filters.html#DynamicThresholdFilter[Dynamic Threshold]
-* xref:/manual/filters.html#MapFilter[Map]
-* xref:/manual/filters.html#MarkerFilter[Marker]
-* xref:/manual/filters.html#MutableThreadContextMapFilter[Mutable Thread Context Map]
-* xref:/manual/filters.html#RegexFilter[Regex]
-* xref:/manual/filters.html#Script[Script]
-* xref:/manual/filters.html#StructuredDataFilter[Structured Data]
-* xref:/manual/filters.html#ThreadContextMapFilter[Thread Context Map]
-* xref:/manual/filters.html#ThresholdFilter[Threshold]
-* xref:/manual/filters.html#TimeFilter[Time]
-
-== Async Loggers
-
-* xref:/manual/async.html[Async Loggers]
-* xref:/manual/async.html#Trade-offs[Trade-offs]
-* xref:/manual/async.html#AllAsync[All Loggers Async]
-* xref:/manual/async.html#MixedSync-Async[Mixed Sync & Async]
-* xref:/manual/async.html#WaitStrategy[WaitStrategy]
-* xref:/manual/async.html#Location[Location]
-* xref:/manual/async.html#Performance[Performance]
-* xref:/manual/async.html#UnderTheHood[Under The Hood]
-
-== Garbage-free Logging
-
-* xref:/manual/garbagefree.html[Garbage-free Logging]
-* xref:/manual/garbagefree.html#Config[Configuration]
-* xref:/manual/garbagefree.html#Appenders[Supported Appenders]
-* xref:/manual/garbagefree.html#Layouts[Supported Layouts]
-* xref:/manual/garbagefree.html#Filters[Supported Filters]
-* xref:/manual/garbagefree.html#api[API Changes]
-* xref:/manual/garbagefree.html#codeImpact[Impact on Application Code]
-* xref:/garbagefree.html#Performance[Performance] /manual
-* xref:/manual/garbagefree.html#UnderTheHood[Under the Hood]
-
-== Extending Log4j
-
-* xref:/manual/extending.html[Extending Log4j]
-* xref:/manual/extending.html#LoggerContextFactory[LoggerContextFactory ]
-* xref:/manual/extending.html#ContextSelector[ContextSelector ]
-* xref:/manual/extending.html#ConfigurationFactory[ConfigurationFactory ]
-* xref:/manual/extending.html#LoggerConfig[LoggerConfig ]
-* xref:/manual/extending.html#LogEventFactory[LogEventFactory ]
-* xref:/manual/extending.html#MessageFactory[MessageFactory ]
-* xref:/manual/extending.html#Lookups[Lookups ]
-* xref:/manual/extending.html#Filters[Filters ]
-* xref:/manual/extending.html#Appenders[Appenders ]
-* xref:/manual/extending.html#Layouts[Layouts ]
-* xref:/manual/extending.html#PatternConverters[PatternConverters ]
-* xref:/manual/extending.html#Plugin_Builders[Plugin Builders]
-* xref:/manual/extending.html#Custom_ContextDataInjector[Custom ContextDataInjector]
-* xref:/manual/extending.html#Custom_Plugins[Custom Plugins]
-
-== Plugins
-
-* xref:/manual/plugins.html[Plugins]
-* xref:/manual/plugins.html#Core[Core ]
-* xref:/manual/plugins.html#Converters[Converters]
-* xref:/manual/plugins.html#KeyProviders[Key Providers]
-* xref:/manual/plugins.html#Lookups[Lookups ]
-* xref:/manual/plugins.html#TypeConverters[Type Converters]
-* xref:/manual/plugins.html#DeveloperNotes[Developer Notes]
-
-
-== Programmatic Log4j Configuration
-
-* xref:/manual/customconfig.html[Programmatic Log4j Configuration]
-* xref:/manual/customconfig.html#ConfigurationBuilder[ConfigurationBuilder API]
-* xref:/manual/customconfig.html#ConfigurationFactory[Understanding ConfigurationFactory]
-* xref:/manual/customconfig.html#Example[Example]
-* xref:/manual/customconfig.html#Configurator[Using Configurator]
-* xref:/manual/customconfig.html#Hybrid[Config File and Code]
-* xref:/manual/customconfig.html#AddingToCurrent[After Initialization]
-* xref:/manual/customconfig.html#AppendingToWritersAndOutputStreams[Appending to Writers & OutputStreams]
-
-== Custom Log Levels
-
-* xref:/manual/customloglevels.html[Custom Log Levels]
-* xref:/manual/customloglevels.html#DefiningLevelsInCode[In Code]
-* xref:/manual/customloglevels.html#DefiningLevelsInConfiguration[In Configuration]
-* xref:/manual/customloglevels.html#AddingOrReplacingLevels[Adding or Replacing Levels]
-* xref:/manual/customloglevels.html#CustomLoggers[Custom Loggers]
-* xref:/manual/customloglevels.html#ExampleUsage[Custom Logger Example]
-* xref:/manual/customloglevels.html#CodeGen[Code Generation Tool]
-
-== Others
-
-* xref:/manual/jmx.html[JMX]
-* xref:/manual/logsep.html[Logging Separation]
-
diff --git a/src/site/antora/modules/ROOT/pages/download.adoc b/src/site/antora/modules/ROOT/pages/download.adoc
index ba80d5145b..35fade8e59 100644
--- a/src/site/antora/modules/ROOT/pages/download.adoc
+++ b/src/site/antora/modules/ROOT/pages/download.adoc
@@ -15,8 +15,6 @@
limitations under the License.
////
-include::_constants.adoc[]
-
= Install Apache Log4j
Apache Log4j is distributed under the
diff --git a/src/site/antora/modules/ROOT/pages/log4j-docker.adoc b/src/site/antora/modules/ROOT/pages/log4j-docker.adoc
index 0fd2155a28..7894465f0b 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-docker.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-docker.adoc
@@ -17,20 +17,18 @@ Licensed to the Apache Software Foundation (ASF) under one or more
limitations under the License.
////
-#set($dollar = '$') #set($h1='#') #set($h2='##')
-
-$h1 Log4j Docker Support
+= Log4j Docker Support
Log4j supports Docker by providing a Lookup to retrieve container information.
-$h2 Accessing Docker
+== Accessing Docker
The Log4j Docker support requires access to the Docker REST interface.
In practical terms this means the application either needs access to unix:///var/run/docker.sock through a volume mount (not recommended), bind Docker to another host/port or unix socket.
or use a proxy application to provide access.
The https://github.com/apache/logging-log4j2/tree/main/log4j-spring-cloud-config/log4j-spring-cloud-config-samples/log4j-spring-cloud-config-sample-application[Log4j Spring Cloud sample application] uses a socat proxy to access Docker.
-$h2 Lookup Attributes
+== Lookup Attributes
Log4j Docker provides access to the following container attributes:
@@ -50,5 +48,5 @@ $D$container
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.
-$h2 Requirements Log4j Docker requires Log4j Core, Log4j API and a minimum of Java 8.
+== Requirements Log4j Docker requires Log4j Core, Log4j API and a minimum of Java 8.
For more information, see link:runtime-dependencies.html[Runtime Dependencies].
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 a68040a619..a0cc7a4786 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc
@@ -17,17 +17,15 @@ Licensed to the Apache Software Foundation (ASF) under one or more
limitations under the License.
////
-#set($dollar = '$') #set($h1='#') #set($h2='##')
-
-$h1 Flume Appender
+= Flume Appender
The Flume Appender allows applications to send events to Flume Agents.
-$h2 Remote Agent
+== Remote Agent
Including the Log4j flume-ng jar in your Maven-based project as a dependency should cause all the transitive dependencies necessary for the remote Agent to function to be included.
-$h2 Persistent Agent
+== Persistent Agent
The persistent agent uses Berkeley DB.
The following dependency should be added to your pom.xml in addition to the log4j-flume-ng dependency.
@@ -60,7 +58,7 @@ The following dependency should be added to your pom.xml in addition to the log4
</repositories>
----
-$h2 Embedded Agent
+== Embedded Agent
The following is a sample pom file for Maven that can be used as a template for integrating the Flume Embedded Appender into an application.
@@ -227,5 +225,5 @@ The following is a sample pom file for Maven that can be used as a template for
</project>
----
-$h2 Requirements The Flume Appender requires the Log4J 2 API.
+== Requirements The Flume Appender requires the Log4J 2 API.
For more information, see link:runtime-dependencies.html[Runtime Dependencies].
diff --git a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
index 16dfc27f61..551c4283aa 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
@@ -16,13 +16,6 @@ Licensed to the Apache Software Foundation (ASF) under one or more
See the License for the specific language governing permissions and
limitations under the License.
////
-:doctype: book
-
-There are two possibilities:
-
-* Logging Adapter as complete replacement (preferred, but requires JVM start option)
-* Bridge Handler, transfering JDK output to log4j, e.g.
-useful for webapps
= Log4j JDK Logging Adapter
@@ -88,7 +81,7 @@ Using the default `LevelConverter` implementation, custom logging levels are map
| `ALL`
|===
-= Log4j JDK Logging Bridge Handler
+== Log4j JDK Logging Bridge Handler
The LogManager is not always useable because you have to set a JVM wide effective system property - e.g.
in web servers this is not possible if you are not the administrator.
diff --git a/src/site/antora/modules/ROOT/pages/log4j-kubernetes.adoc b/src/site/antora/modules/ROOT/pages/log4j-kubernetes.adoc
index f3757ceefe..dd1f73f10d 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-kubernetes.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-kubernetes.adoc
@@ -17,20 +17,18 @@ Licensed to the Apache Software Foundation (ASF) under one or more
limitations under the License.
////
-#set($dollar = '$') #set($h1='#') #set($h2='##')
-
-$h1 Log4j Kubernetes Support
+= Log4j Kubernetes Support
Log4j supports Kubernetes by providing a Lookup to retrieve container information.
-$h2 Accessing Kubernetes
+== Accessing Kubernetes
The Log4j Kubernetes support requires access to the Docker REST interface.
In many cases the REST service can be accessed automatically.
If needed the Kubernetes client can be configured any of the standard Log4j configuration locations or via the Spring Boot configuration.
Note, however, that since Spring Boot causes logging to initialize 3 times and since the Spring environment is only available during the last Log4j initialization Spring properties will only be available to Log4j in the last initialization.
-$h2 Lookup Attributes
+== Lookup Attributes
Log4j Kubernetes provides access to the following container attributes:
@@ -61,7 +59,7 @@ $D$container
to the configuration.
Note that kubernetes variables are only resolved once during logging initialization so they shouldn't be referenced with more than one '$' character.
-$h2 Configuration
+== Configuration
Much of the configuration needed to access the Kubernetes API server is provided automatically by Kubernetes.
However, it is not uncommon to need to provide the url required to access the Kubernetes API server or the namespace the application is assigned to.
@@ -198,5 +196,5 @@ Note that Spring Boot initializes logging 3 times and only the last will have a
| Reconnect Interval limit retries
|===
-$h2 Requirements Log4j Kubernetes requires Log4j Core, Log4j API and a minimum of Java 8.
+== Requirements Log4j Kubernetes requires Log4j Core, Log4j API and a minimum of Java 8.
For more information, see link:runtime-dependencies.html[Runtime Dependencies].
diff --git a/src/site/antora/modules/ROOT/pages/log4j-mongodb4.adoc b/src/site/antora/modules/ROOT/pages/log4j-mongodb4.adoc
index b95e2f9bc7..2620b14941 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-mongodb4.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-mongodb4.adoc
@@ -17,11 +17,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
limitations under the License.
////
-#set($h1='#') #set($h2='##')
-
-== TODO: use properties for dynamic dependency versions
-
-$h1 MongoDB appender
+= MongoDB appender
http://www.mongodb.org/[MongoDB] is supported through the http://docs.mongodb.org/ecosystem/drivers/java/[Java MongoDB Driver].
@@ -43,7 +39,7 @@ http://www.mongodb.org/[MongoDB] is supported through the http://docs.mongodb.or
</dependencies>
----
-$h2 Requirements
+== Requirements
The MongoDB Appender is dependent on the Log4j 2 API and implementation.
For more information, see link:runtime-dependencies.html[Runtime Dependencies].
diff --git a/src/site/antora/modules/manual/pages/api-separation.adoc b/src/site/antora/modules/ROOT/pages/manual/api-separation.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/api-separation.adoc
rename to src/site/antora/modules/ROOT/pages/manual/api-separation.adoc
diff --git a/src/site/antora/modules/manual/pages/api.adoc b/src/site/antora/modules/ROOT/pages/manual/api.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/api.adoc
rename to src/site/antora/modules/ROOT/pages/manual/api.adoc
diff --git a/src/site/antora/modules/manual/pages/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/appenders.adoc
rename to src/site/antora/modules/ROOT/pages/manual/appenders.adoc
diff --git a/src/site/antora/modules/manual/pages/architecture.adoc b/src/site/antora/modules/ROOT/pages/manual/architecture.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/architecture.adoc
rename to src/site/antora/modules/ROOT/pages/manual/architecture.adoc
diff --git a/src/site/antora/modules/manual/pages/async.adoc b/src/site/antora/modules/ROOT/pages/manual/async.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/async.adoc
rename to src/site/antora/modules/ROOT/pages/manual/async.adoc
diff --git a/src/site/antora/modules/manual/pages/cloud.adoc b/src/site/antora/modules/ROOT/pages/manual/cloud.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/cloud.adoc
rename to src/site/antora/modules/ROOT/pages/manual/cloud.adoc
diff --git a/src/site/antora/modules/manual/pages/compatibility.adoc b/src/site/antora/modules/ROOT/pages/manual/compatibility.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/compatibility.adoc
rename to src/site/antora/modules/ROOT/pages/manual/compatibility.adoc
diff --git a/src/site/antora/modules/manual/pages/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/configuration.adoc
rename to src/site/antora/modules/ROOT/pages/manual/configuration.adoc
diff --git a/src/site/antora/modules/manual/pages/customconfig.adoc b/src/site/antora/modules/ROOT/pages/manual/customconfig.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/customconfig.adoc
rename to src/site/antora/modules/ROOT/pages/manual/customconfig.adoc
diff --git a/src/site/antora/modules/manual/pages/customloglevels.adoc b/src/site/antora/modules/ROOT/pages/manual/customloglevels.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/customloglevels.adoc
rename to src/site/antora/modules/ROOT/pages/manual/customloglevels.adoc
diff --git a/src/site/antora/modules/manual/pages/eventlogging.adoc b/src/site/antora/modules/ROOT/pages/manual/eventlogging.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/eventlogging.adoc
rename to src/site/antora/modules/ROOT/pages/manual/eventlogging.adoc
diff --git a/src/site/antora/modules/manual/pages/extending.adoc b/src/site/antora/modules/ROOT/pages/manual/extending.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/extending.adoc
rename to src/site/antora/modules/ROOT/pages/manual/extending.adoc
diff --git a/src/site/antora/modules/manual/pages/filters.adoc b/src/site/antora/modules/ROOT/pages/manual/filters.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/filters.adoc
rename to src/site/antora/modules/ROOT/pages/manual/filters.adoc
diff --git a/src/site/antora/modules/manual/pages/flowtracing.adoc b/src/site/antora/modules/ROOT/pages/manual/flowtracing.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/flowtracing.adoc
rename to src/site/antora/modules/ROOT/pages/manual/flowtracing.adoc
diff --git a/src/site/antora/modules/manual/pages/garbagefree.adoc b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/garbagefree.adoc
rename to src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
diff --git a/src/site/antora/modules/ROOT/pages/manual/index.adoc b/src/site/antora/modules/ROOT/pages/manual/index.adoc
new file mode 100644
index 0000000000..9015a4969f
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/manual/index.adoc
@@ -0,0 +1,210 @@
+////
+ 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.
+////
+= Documentation
+
+* xref:manual/architecture.adoc[Architecture]
+* xref:manual/migration.adoc[Log4j 1.x Migration]
+
+== Java API
+
+* xref:manual/api.adoc[Java API]
+* xref:manual/logbuilder.adoc[Log Builder]
+* xref:manual/flowtracing.adoc[Flow Tracing]
+* xref:manual/markers.adoc[Markers]
+* xref:manual/eventlogging.adoc[Event Logging]
+* xref:manual/messages.adoc[Messages]
+* xref:manual/thread-context.adoc[ThreadContext]
+
+== xref:manual/configuration.adoc[Configuration]
+
+* xref:manual/configuration.adoc#Architecture[Configuration Architecture]
+* xref:manual/configuration.adoc#Arbiters[Arbiters]
+* xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration]
+* xref:manual/configuration.adoc#Additivity[Additivity]
+* xref:manual/configuration.adoc#AutomaticReconfiguration[Automatic Reconfiguration]
+* xref:manual/configuration.adoc#ChainsawSupport[Chainsaw Support]
+* xref:manual/configuration.adoc#ConfigurationSyntax[Configuration Syntax]
+* xref:manual/configuration.adoc#XML[XML Syntax]
+* xref:manual/configuration.adoc#JSON[JSON Syntax]
+* xref:manual/configuration.adoc#YAML[YAML Syntax]
+* xref:manual/configuration.adoc#Properties[Properties Syntax]
+* xref:manual/configuration.adoc#Loggers[Configuring Loggers]
+* xref:manual/configuration.adoc#Appenders[Configuring Appenders]
+* xref:manual/configuration.adoc#Filters[Configuring Filters]
+* xref:manual/configuration.adoc#PropertySubstitution[Property Substitution]
+* xref:manual/configuration.adoc#RuntimeLookup[Lookup Variables]
+* xref:manual/configuration.adoc#Scripts[Scripts]
+* xref:manual/configuration.adoc#XInclude[XInclude]
+* xref:manual/configuration.adoc#CompositeConfiguration[Composite Configurations]
+* xref:manual/configuration.adoc#StatusMessages[Status Messages]
+* xref:manual/configuration.adoc#UnitTestingInMaven[Unit Testing]
+
+== xref:manual/usage.adoc[Usage]
+
+* xref:/manual/usage.html?#StaticVsNonStatic[Static vs non-Static Loggers]
+* xref:/manual/usage.html?#LoggerVsClass[Logger Name vs Class Name]
+* xref:manual/cloud.adoc[Logging in the Cloud]
+
+== xref:/performance.html[Performance]
+
+* xref:/performance.html#benchmarks[Benchmarks]
+* xref:/performance.html#loglibComparison[Logging Library Comparison]
+* xref:/performance.html#asyncLogging[Async Logging Comparison]
+* xref:/performance.html#asyncLoggingResponseTime[Async Logging Latency]
+* xref:/performance.html#asyncLoggingWithParams[Parameters]
+* xref:/performance.html#asyncLoggingWithLocation[Location]
+* xref:/performance.html#fileLoggingComparison[File Logging Comparison]
+* xref:/performance.html#filtering[Filtering Comparison]
+* xref:/performance.html#tradeoffs[Trade-offs]
+
+== xref:manual/lookups.adoc[Lookups]
+
+* xref:manual/lookups.adoc#ContextMapLookup[Context Map]
+* xref:manual/lookups.adoc#DateLookup[Date]
+* xref:manual/lookups.adoc#DockerLookup[Docker]
+* xref:manual/lookups.adoc#EnvironmentLookup[Environment]
+* xref:manual/lookups.adoc#EventLookup[Event]
+* xref:manual/lookups.adoc#JavaLookup[Java]
+* xref:manual/lookups.adoc#JndiLookup[JNDI]
+* xref:manual/lookups.adoc#JmxRuntimeInputArgumentsLookup[JVM Arguments]
+* xref:manual/lookups.adoc#KubernetesLookup[Kubernetes]
+* xref:manual/lookups.adoc#Log4jConfigLookup[Log4j Config]
+* xref:manual/lookups.adoc#LowerLookup[Lower]
+* xref:manual/lookups.adoc#AppMainArgsLookup[Main Arguments]
+* xref:manual/lookups.adoc#MapLookup[Map]
+* xref:manual/lookups.adoc#StructuredDataLookup[Structured Data]
+* xref:manual/lookups.adoc#SystemPropertiesLookup[System Properties]
+* xref:manual/lookups.adoc#UpperLookup[Upper]
+
+== xref:manual/appenders.adoc[Appenders]
+
+* xref:manual/appenders.adoc#AsyncAppender[Async]
+* xref:manual/appenders.adoc#ConsoleAppender[Console]
+* xref:manual/appenders.adoc#FailoverAppender[Failover]
+* xref:manual/appenders.adoc#FileAppender[File]
+* xref:manual/appenders.adoc#FlumeAppender[Flume]
+* xref:manual/appenders.adoc#JDBCAppender[JDBC]
+* xref:manual/appenders.adoc#HttpAppender[HTTP]
+* xref:manual/appenders.adoc#MemoryMappedFileAppender[Memory Mapped File]
+* xref:manual/appenders.adoc#NoSQLAppender[NoSQL]
+* xref:manual/appenders.adoc#NoSQLAppenderMongoDB[NoSQL for MongoDB]
+* xref:manual/appenders.adoc#OutputStreamAppender[Output Stream]
+* xref:manual/appenders.adoc#RandomAccessFileAppender[Random Access File]
+* xref:manual/appenders.adoc#RewriteAppender[Rewrite]
+* xref:manual/appenders.adoc#RollingFileAppender[Rolling File]
+* xref:manual/appenders.adoc#RollingRandomAccessFileAppender[Rolling Random Access File]
+* xref:manual/appenders.adoc#RoutingAppender[Routing]
+* xref:manual/appenders.adoc#ScriptAppenderSelector[ScriptAppenderSelector]
+* xref:manual/appenders.adoc#SocketAppender[Socket]
+* xref:manual/appenders.adoc#SSL[SSL]
+* xref:manual/appenders.adoc#SyslogAppender[Syslog]
+
+== xref:manual/layouts.adoc[Layouts]
+
+* xref:manual/layouts.adoc#CSVLayouts[CSV]
+* xref:manual/layouts.adoc#HTMLLayout[HTML]
+* xref:manual/json-template-layout.adoc[JSON Template]
+* xref:manual/layouts.adoc#PatternLayout[Pattern]
+* xref:manual/layouts.adoc#RFC5424Layout[RFC-5424]
+* xref:manual/layouts.adoc#SerializedLayout[Serialized]
+* xref:manual/layouts.adoc#SyslogLayout[Syslog]
+* xref:manual/layouts.adoc#LocationInformation[Location Information]
+
+== xref:manual/filters.adoc[Filters]
+
+* xref:manual/filters.adoc#BurstFilter[Burst]
+* xref:manual/filters.adoc#CompositeFilter[Composite Filter]
+* xref:manual/filters.adoc#DynamicThresholdFilter[Dynamic Threshold]
+* xref:manual/filters.adoc#MapFilter[Map]
+* xref:manual/filters.adoc#MarkerFilter[Marker]
+* xref:manual/filters.adoc#MutableThreadContextMapFilter[Mutable Thread Context Map]
+* xref:manual/filters.adoc#RegexFilter[Regex]
+* xref:manual/filters.adoc#Script[Script]
+* xref:manual/filters.adoc#StructuredDataFilter[Structured Data]
+* xref:manual/filters.adoc#ThreadContextMapFilter[Thread Context Map]
+* xref:manual/filters.adoc#ThresholdFilter[Threshold]
+* xref:manual/filters.adoc#TimeFilter[Time]
+
+== xref:manual/async.adoc[Async Loggers]
+
+* xref:manual/async.adoc#Trade-offs[Trade-offs]
+* xref:manual/async.adoc#AllAsync[All Loggers Async]
+* xref:manual/async.adoc#MixedSync-Async[Mixed Sync & Async]
+* xref:manual/async.adoc#WaitStrategy[WaitStrategy]
+* xref:manual/async.adoc#Location[Location]
+* xref:manual/async.adoc#Performance[Performance]
+* xref:manual/async.adoc#UnderTheHood[Under The Hood]
+
+== xref:manual/garbagefree.adoc[Garbage-free Logging]
+
+* xref:manual/garbagefree.adoc#Config[Configuration]
+* xref:manual/garbagefree.adoc#Appenders[Supported Appenders]
+* xref:manual/garbagefree.adoc#Layouts[Supported Layouts]
+* xref:manual/garbagefree.adoc#Filters[Supported Filters]
+* xref:manual/garbagefree.adoc#api[API Changes]
+* xref:manual/garbagefree.adoc#codeImpact[Impact on Application Code]
+* xref:manual/garbagefree.adoc#UnderTheHood[Under the Hood]
+
+== xref:manual/extending.adoc[Extending Log4j]
+
+* xref:manual/extending.adoc#LoggerContextFactory[`LoggerContextFactory`]
+* xref:manual/extending.adoc#ContextSelector[`ContextSelector`]
+* xref:manual/extending.adoc#ConfigurationFactory[`ConfigurationFactory`]
+* xref:manual/extending.adoc#LoggerConfig[`LoggerConfig`]
+* xref:manual/extending.adoc#LogEventFactory[`LogEventFactory`]
+* xref:manual/extending.adoc#MessageFactory[`MessageFactory`]
+* xref:manual/extending.adoc#Lookups[Lookups]
+* xref:manual/extending.adoc#Filters[Filters]
+* xref:manual/extending.adoc#Appenders[Appenders]
+* xref:manual/extending.adoc#Layouts[Layouts]
+* xref:manual/extending.adoc#PatternConverters[Pattern converters]
+* xref:manual/extending.adoc#Plugin_Builders[Plugin builders]
+* xref:manual/extending.adoc#Custom_ContextDataProvider[Custom `ContextDataProvider`]
+* xref:manual/extending.adoc#Custom_Plugins[Custom plugins]
+
+== xref:manual/plugins.adoc[Plugins]
+
+* xref:manual/plugins.adoc#Core[Core]
+* xref:manual/plugins.adoc#Converters[Converters]
+* xref:manual/plugins.adoc#KeyProviders[Key Providers]
+* xref:manual/plugins.adoc#Lookups[Lookups]
+* xref:manual/plugins.adoc#TypeConverters[Type Converters]
+* xref:manual/plugins.adoc#DeveloperNotes[Developer Notes]
+
+
+== xref:manual/customconfig.adoc[Programmatic Log4j Configuration]
+
+* xref:manual/customconfig.adoc#ConfigurationBuilder[ConfigurationBuilder API]
+* xref:manual/customconfig.adoc#ConfigurationFactory[Understanding ConfigurationFactory]
+* xref:manual/customconfig.adoc#Example[Example]
+* xref:manual/customconfig.adoc#Configurator[Using Configurator]
+* xref:manual/customconfig.adoc#Hybrid[Config File and Code]
+* xref:manual/customconfig.adoc#AddingToCurrent[After Initialization]
+* xref:manual/customconfig.adoc#AppendingToWritersAndOutputStreams[Appending to Writers & OutputStreams]
+
+== xref:manual/customloglevels.adoc#DefiningLevelsInCode[In Code]
+
+* xref:manual/customloglevels.adoc#DefiningLevelsInConfiguration[In Configuration]
+* xref:manual/customloglevels.adoc#AddingOrReplacingLevels[Adding or Replacing Levels]
+* xref:manual/customloglevels.adoc#CustomLoggers[Custom Loggers]
+* xref:manual/customloglevels.adoc#ExampleUsage[Custom Logger Example]
+* xref:manual/customloglevels.adoc#CodeGen[Code Generation Tool]
+
+== Others
+
+* xref:manual/jmx.adoc[JMX]
+* xref:manual/logsep.adoc[Logging Separation]
diff --git a/src/site/antora/modules/manual/pages/jmx.adoc b/src/site/antora/modules/ROOT/pages/manual/jmx.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/jmx.adoc
rename to src/site/antora/modules/ROOT/pages/manual/jmx.adoc
diff --git a/src/site/antora/modules/manual/pages/json-template-layout.adoc b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
similarity index 99%
rename from src/site/antora/modules/manual/pages/json-template-layout.adoc
rename to src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
index 217d4ee89d..eb25d3aea1 100644
--- a/src/site/antora/modules/manual/pages/json-template-layout.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
@@ -17,8 +17,6 @@
= JSON Template Layout
Volkan Yazıcı <vy...@apache.org>
-include::../_constants.adoc[]
-
`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON
generating layout. It encodes ``LogEvent``s according to the structure described
by the JSON template provided. In a nutshell, it shines with its
diff --git a/src/site/antora/modules/manual/pages/layouts.adoc b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/layouts.adoc
rename to src/site/antora/modules/ROOT/pages/manual/layouts.adoc
diff --git a/src/site/antora/modules/manual/pages/logbuilder.adoc b/src/site/antora/modules/ROOT/pages/manual/logbuilder.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/logbuilder.adoc
rename to src/site/antora/modules/ROOT/pages/manual/logbuilder.adoc
diff --git a/src/site/antora/modules/manual/pages/logsep.adoc b/src/site/antora/modules/ROOT/pages/manual/logsep.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/logsep.adoc
rename to src/site/antora/modules/ROOT/pages/manual/logsep.adoc
diff --git a/src/site/antora/modules/manual/pages/lookups.adoc b/src/site/antora/modules/ROOT/pages/manual/lookups.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/lookups.adoc
rename to src/site/antora/modules/ROOT/pages/manual/lookups.adoc
diff --git a/src/site/antora/modules/manual/pages/markers.adoc b/src/site/antora/modules/ROOT/pages/manual/markers.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/markers.adoc
rename to src/site/antora/modules/ROOT/pages/manual/markers.adoc
diff --git a/src/site/antora/modules/manual/pages/messages.adoc b/src/site/antora/modules/ROOT/pages/manual/messages.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/messages.adoc
rename to src/site/antora/modules/ROOT/pages/manual/messages.adoc
diff --git a/src/site/antora/modules/manual/pages/migration.adoc b/src/site/antora/modules/ROOT/pages/manual/migration.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/migration.adoc
rename to src/site/antora/modules/ROOT/pages/manual/migration.adoc
diff --git a/src/site/antora/modules/manual/pages/plugins.adoc b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
similarity index 98%
rename from src/site/antora/modules/manual/pages/plugins.adoc
rename to src/site/antora/modules/ROOT/pages/manual/plugins.adoc
index 6014db37dc..7deb8808d8 100644
--- a/src/site/antora/modules/manual/pages/plugins.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
@@ -14,13 +14,11 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-# Log4j 2 Plugins
+= Plugins
+Ralph Goers `<rg...@apache.org>`
+Matt Sicker `<ma...@apache.org>`
-**Authors:** Ralph Goers `<rg...@apache.org>`, Matt Sicker `<ma...@apache.org>`
-
-## Plugins
-
-### Introduction
+== Introduction
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.
diff --git a/src/site/antora/modules/manual/pages/thread-context.adoc b/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/thread-context.adoc
rename to src/site/antora/modules/ROOT/pages/manual/thread-context.adoc
diff --git a/src/site/antora/modules/manual/pages/usage.adoc b/src/site/antora/modules/ROOT/pages/manual/usage.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/usage.adoc
rename to src/site/antora/modules/ROOT/pages/manual/usage.adoc
diff --git a/src/site/antora/modules/manual/pages/webapp.adoc b/src/site/antora/modules/ROOT/pages/manual/webapp.adoc
similarity index 100%
rename from src/site/antora/modules/manual/pages/webapp.adoc
rename to src/site/antora/modules/ROOT/pages/manual/webapp.adoc
diff --git a/src/site/antora/modules/manual/pages/index.adoc b/src/site/antora/modules/manual/pages/index.adoc
deleted file mode 100644
index 57af253654..0000000000
--- a/src/site/antora/modules/manual/pages/index.adoc
+++ /dev/null
@@ -1,138 +0,0 @@
-////
- 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.
-////
-= Overview
-Ralph Goers <rg...@apache.org>
-
-== Welcome to Log4j!
-
-Almost every large application includes its own logging or tracing API.
-In conformance with this rule, the E.U. http://www.semper.org[SEMPER]
-project decided to write its own tracing API. This was in early 1996.
-After countless enhancements, several incarnations and much work that
-API has evolved to become log4j, a popular logging package for Java. The
-package is distributed under the link:../LICENSE[Apache Software
-License], a fully-fledged open source license certified by the
-http://www.opensource.org[open source] initiative. The latest log4j
-version, including full-source code, class files and documentation can
-be found at
-https://logging.apache.org/log4j/2.x/index.html[*https://logging.apache.org/log4j/2.x/index.html*].
-
-Inserting log statements into code is a low-tech method for debugging
-it. It may also be the only way because debuggers are not always
-available or applicable. This is usually the case for multithreaded
-applications and distributed applications at large.
-
-Experience indicates that logging was an important component of the
-development cycle. It offers several advantages. It provides precise
-_context_ about a run of the application. Once inserted into the code,
-the generation of logging output requires no human intervention.
-Moreover, log output can be saved in persistent medium to be studied at
-a later time. In addition to its use in the development cycle, a
-sufficiently rich logging package can also be viewed as an auditing
-tool.
-
-As Brian W. Kernighan and Rob Pike put it in their truly excellent book
-_"The Practice of Programming":_
-
-____
-As personal choice, we tend not to use debuggers beyond getting a stack
-trace or the value of a variable or two. One reason is that it is easy
-to get lost in details of complicated data structures and control flow;
-we find stepping through a program less productive than thinking harder
-and adding output statements and self-checking code at critical places.
-Clicking over statements takes longer than scanning the output of
-judiciously-placed displays. It takes less time to decide where to put
-print statements than to single-step to the critical section of code,
-even assuming we know where that is. More important, debugging
-statements stay with the program; debugging sessions are transient.
-____
-
-Logging does have its drawbacks. It can slow down an application. If too
-verbose, it can cause scrolling blindness. To alleviate these concerns,
-log4j is designed to be reliable, fast and extensible. Since logging is
-rarely the main focus of an application, the log4j API strives to be
-simple to understand and to use.
-
-== Log4j 2
-
-Log4j 1.x has been widely adopted and used in many applications.
-However, through the years development on it has slowed down. It has
-become more difficult to maintain due to its need to be compliant with
-very old versions of Java and became
-https://blogs.apache.org/foundation/entry/apache_logging_services_project_announces[End
-of Life] in August 2015. Its alternative, SLF4J/Logback made many needed
-improvements to the framework. So why bother with Log4j 2? Here are a
-few of the reasons.
-
-1. Log4j 2 is designed to be usable as an audit logging framework. Both
-Log4j 1.x and Logback will lose events while reconfiguring. Log4j 2 will
-not. In Logback, exceptions in Appenders are never visible to the
-application. In Log4j 2 Appenders can be configured to allow the
-exception to percolate to the application.
-2. Log4j 2 contains next-generation link:async.html[Asynchronous
-Loggers] based on the https://lmax-exchange.github.io/disruptor/[LMAX
-Disruptor library]. In multi-threaded scenarios Asynchronous Loggers
-have 10 times higher throughput and orders of magnitude lower latency
-than Log4j 1.x and Logback.
-3. Log4j 2 is link:garbagefree.html[garbage free] for stand-alone
-applications, and low garbage for web applications during steady state
-logging. This reduces pressure on the garbage collector and can give
-better response time performance.
-4. Log4j 2 uses a link:plugins.html[Plugin system] that makes it
-extremely easy to link:extending.html[extend the framework] by adding
-new link:appenders.html[Appenders], link:filters.html[Filters],
-link:layouts.html[Layouts], link:lookups.html[Lookups], and Pattern
-Converters without requiring any changes to Log4j.
-5. Due to the Plugin system configuration is simpler. Entries in the
-configuration do not require a class name to be specified.
-6. Support for link:customloglevels.html[custom log levels]. Custom log
-levels can be defined in code or in configuration.
-7. Support for link:api.html#LambdaSupport[lambda expressions]. Client
-code running on Java 8 can use lambda expressions to lazily construct a
-log message only if the requested log level is enabled. Explicit level
-checks are not needed, resulting in cleaner code.
-8. Support for link:messages.html[Message objects]. Messages allow
-support for interesting and complex constructs to be passed through the
-logging system and be efficiently manipulated. Users are free to create
-their own `Message` types and write custom link:layouts.html[Layouts],
-link:filters.html[Filters] and link:lookups.html[Lookups] to manipulate
-them.
-9. Log4j 1.x supports Filters on Appenders. Logback added TurboFilters
-to allow filtering of events before they are processed by a Logger.
-Log4j 2 supports Filters that can be configured to process events before
-they are handled by a Logger, as they are processed by a Logger or on an
-Appender.
-10. Many Logback Appenders do not accept a Layout and will only send
-data in a fixed format. Most Log4j 2 Appenders accept a Layout, allowing
-the data to be transported in any format desired.
-11. Layouts in Log4j 1.x and Logback return a String. This resulted in
-the problems discussed at
-http://logback.qos.ch/manual/encoders.html[Logback Encoders]. Log4j 2
-takes the simpler approach that link:layouts.html[Layouts] always return
-a byte array. This has the advantage that it means they can be used in
-virtually any Appender, not just the ones that write to an OutputStream.
-12. The link:appenders.html#SyslogAppender[Syslog Appender] supports
-both TCP and UDP as well as support for the BSD syslog and the
-http://tools.ietf.org/html/rfc5424[RFC 5424] formats.
-13. Log4j 2 takes advantage of Java 5 concurrency support and performs
-locking at the lowest level possible. Log4j 1.x has known deadlock
-issues. Many of these are fixed in Logback but many Logback classes
-still require synchronization at a fairly high level.
-14. It is an Apache Software Foundation project following the community
-and support model used by all ASF projects. If you want to contribute or
-gain the right to commit changes just follow the path outlined at
-http://jakarta.apache.org/site/contributing.html[Contributing].