Revamp rolling file appender documentation

We split the documentation of rolling file appenders and minimize the repetition of configuration option descriptions and examples.

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-compress.version>1.26.2</site-commons-compress.version>
     <site-commons-csv.version>1.11.0</site-commons-csv.version>
     <site-commons-logging.version>1.3.3</site-commons-logging.version>
     <site-disruptor.version>4.0.0</site-disruptor.version>
@@ -728,6 +729,12 @@
 
           <!-- Other dependencies -->
 
+          <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-compress</artifactId>
+            <version>${site-commons-compress.version}</version>
+          </dependency>
+
           <dependency>
             <groupId>org.apache.commons</groupId>
             <artifactId>commons-csv</artifactId>

src/site/antora/antora.tmpl.yml

@@ -51,6 +51,7 @@ asciidoc:
     lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor/"
     slf4j-url: "https://www.slf4j.org"
     # Dependency versions
+    commons-compress-version: "${site-commons-compress.version}"
     commons-csv-version: "${site-commons-csv.version}"
     commons-logging-version: "${site-commons-logging.version}"
     disruptor-version: "${site-disruptor.version}"

src/site/antora/antora.yml

@@ -51,6 +51,7 @@ asciidoc:
     lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor/"
     slf4j-url: "https://www.slf4j.org"
     # Dependency versions
+    commons-compress-version: "1.2.3-commons-compress"
     commons-csv-version: "1.2.3-commons-csv"
     commons-logging-version: "1.2.3-commons-logging"
     disruptor-version: "1.2.3-disruptor"

src/site/antora/modules/ROOT/examples/manual/rolling-file/logrotate.json

@@ -0,0 +1,33 @@
+{
+  "Configuration": {
+    "Appenders": {
+      // tag::appender[]
+      "RollingFile": {
+        "name": "FILE",
+        "fileName": "/var/log/app.log",
+        "filePattern": "/var/log/app.log.%i.gz", // <1>
+        "JsonTemplateLayout": {},
+        "DefaultRolloverStrategy": {
+          "max": 15 // <2>
+        },
+        "Policies": {
+          "CronTriggeringPolicy": {
+            "schedule": "0 0 0 * * ?" // <3>
+          },
+          "SizeBasedTriggeringPolicy": {
+            "size": "100k" // <4>
+          }
+        }
+      }
+      // end::appender[]
+    },
+    "Loggers": {
+      "Root": {
+        "level": "INFO",
+        "AppenderRef": {
+          "ref": "FILE"
+        }
+      }
+    }
+  }
+}

src/site/antora/modules/ROOT/examples/manual/rolling-file/logrotate.properties

@@ -0,0 +1,41 @@
+#
+# 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.
+#
+##
+# tag::appender[]
+appender.0.type = RollingFile
+appender.0.name = FILE
+appender.0.fileName = /var/log/app.log
+# <1>
+appender.0.filePattern = /var/log/app.log.%i.gz
+
+appender.0.layout.type = JsonTemplateLayout
+
+appender.0.strategy.type = DefaultRolloveStrategy
+# <2>
+appender.0.strategy.max = 15
+
+appender.0.policy.type = Policies
+appender.0.policy.0.type = CronTriggeringPolicy
+# <3>
+appender.0.policy.0.schedule = 0 0 0 * * ?
+appender.0.policy.1.type = SizeBasedTriggeringPolicy
+# <4>
+appender.0.policy.1.size = 100k
+# end::appender[]
+
+rootLogger.level = INFO
+rootLogger.appenderRef.0.ref = FILE

src/site/antora/modules/ROOT/examples/manual/rolling-file/logrotate.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ 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.
+  -->
+<Configuration xmlns="https://logging.apache.org/xml/ns"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:schemaLocation="
+                   https://logging.apache.org/xml/ns
+                   https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+  <Appenders>
+    <!-- tag::appender[] -->
+    <RollingFile name="FILE"
+                 fileName="/var/log/app.log"
+                 filePattern="/var/log/app.log.%i.gz"> <!--1-->
+      <JsonTemplateLayout/>
+      <DefaultRolloverStrategy max="15"/> <!--2-->
+      <Policies>
+        <CronTriggeringPolicy schedule="0 0 0 * * ?"/> <!--3-->
+        <SizeBasedTriggeringPolicy size="100k"/> <!--4-->
+      </Policies>
+    </RollingFile>
+    <!-- end::appender[] -->
+  </Appenders>
+  <Loggers>
+    <Root level="INFO">
+      <AppenderRef ref="FILE"/>
+    </Root>
+  </Loggers>
+</Configuration>

src/site/antora/modules/ROOT/examples/manual/rolling-file/logrotate.yaml

@@ -0,0 +1,37 @@
+#
+# 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.
+#
+Configuration:
+  Appenders:
+    # tag::appender[]
+    RollingFile:
+      name: "FILE"
+      fileName: "/var/log/app.log"
+      filePattern: "/var/log/app.log.%i.gz" # <1>
+      JsonTemplateLayout: {}
+      DefaultRolloverStrategy:
+        max: 15 # <2>
+      Policies:
+        CronTriggeringPolicy:
+          schedule: "0 0 0 * * ?" # <3>
+        SizeBasedTriggeringPolicy:
+          size: "100k" # <4>
+    # end::appender[]
+  Loggers:
+    Root:
+      level: "INFO"
+      AppenderRef:
+        ref: "FILE"

src/site/antora/modules/ROOT/examples/manual/rolling-file/per-month.json

@@ -0,0 +1,31 @@
+{
+  "Configuration": {
+    "Appenders": {
+      // tag::appender[]
+      "RollingFile": {
+        "name": "FILE",
+        "filePattern": "/var/log/app/%{yyyy-MM}/%d{yyyy-MM-dd}.log.gz", // <1>
+        "JsonTemplateLayout": {},
+        "DirectWriteRolloverStrategy": {
+          "Delete": {
+            "basePath": "/var/log/app",
+            "maxDepth": 2, // <2>
+            "IfLastModified": {
+              "age": "P90D"
+            }
+          }
+        },
+        "TimeBasedTriggeringPolicy": {}
+      }
+      // end::appender[]
+    },
+    "Loggers": {
+      "Root": {
+        "level": "INFO",
+        "AppenderRef": {
+          "ref": "FILE"
+        }
+      }
+    }
+  }
+}

src/site/antora/modules/ROOT/examples/manual/rolling-file/per-month.properties

@@ -0,0 +1,38 @@
+#
+# 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.
+#
+##
+# tag::appender[]
+appender.0.type = RollingFile
+appender.0.name = FILE
+# <1>
+appender.0.filePattern = /var/log/app/%d{yyyy-MM]/%d{yyyy-MM-dd}.log.gz
+
+appender.0.layout.type = JsonTemplateLayout
+
+appender.0.strategy.type = DirectWriteRolloverStrategy
+appender.0.strategy.delete.type = Delete
+appender.0.strategy.delete.basePath = /var/log/app
+# <2>
+appender.0.strategy.delete.maxDepth = 2
+appender.0.strategy.delete.0.type = IfLastModified
+appender.0.strategy.delete.0.age = P90D
+
+appender.0.policy.type = TimeBaseTriggeringPolicy
+# end::appender[]
+
+rootLogger.level = INFO
+rootLogger.appenderRef.0.ref = FILE

src/site/antora/modules/ROOT/examples/manual/rolling-file/per-month.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ 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.
+  -->
+<Configuration xmlns="https://logging.apache.org/xml/ns"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:schemaLocation="
+                   https://logging.apache.org/xml/ns
+                   https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+  <Appenders>
+    <!-- tag::appender[] -->
+    <RollingFile name="FILE"
+                 filePattern="/var/log/app/%d{yyyy-MM}/%d{yyyy-MM-dd}.log.gz"> <!--1-->
+      <JsonTemplateLayout/>
+      <DirectWriteRolloverStrategy>
+        <Delete basePath="/var/log/app"
+                maxDepth="2"> <!--2-->
+          <IfLastModified age="P90D"/>
+        </Delete>
+      </DirectWriteRolloverStrategy>
+      <TimeBasedTriggeringPolicy/>
+    </RollingFile>
+    <!-- end::appender[] -->
+  </Appenders>
+  <Loggers>
+    <Root level="INFO">
+      <AppenderRef ref="FILE"/>
+    </Root>
+  </Loggers>
+</Configuration>

src/site/antora/modules/ROOT/examples/manual/rolling-file/per-month.yaml

@@ -0,0 +1,36 @@
+#
+# 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.
+#
+Configuration:
+  Appenders:
+    # tag::appender[]
+    RollingFile:
+      name: "FILE"
+      filePattern: "/var/log/app/%d{yyyy-MM}/%d{yyyy-MM-dd}.log.gz" # <1>
+      JsonTemplateLayout: {}
+      DirectWriteRolloverStrategy:
+        Delete:
+          basePath: "/var/log/app"
+          maxDepth: 2 # <2>
+          IfLastModified:
+            age: "P90D"
+      TimeBasedTriggeringPolicy: {}
+    # end::appender[]
+  Loggers:
+    Root:
+      level: "INFO"
+      AppenderRef:
+        ref: "FILE"

src/site/antora/modules/ROOT/examples/manual/rolling-file/policies.json

@@ -0,0 +1,27 @@
+{
+  "Configuration": {
+    "Appenders": {
+      // tag::appender[]
+      "RollingFile": {
+        "name": "FILE",
+        "fileName": "app.log",
+        "filePattern": "app.%d{yyyy-MM-dd}.%i.log",
+        "JsonTemplateLayout": {},
+        "Policies": {
+          "OnStartupTriggeringPolicy": {},
+          "SizeBasedTriggeringPolicy": {},
+          "TimeBasedTriggeringPolicy": {}
+        }
+      }
+      // end::appender[]
+    },
+    "Loggers": {
+      "Root": {
+        "level": "INFO",
+        "AppenderRef": {
+          "ref": "FILE"
+        }
+      }
+    }
+  }
+}