Revamp cloud.adoc for service-oriented architectures

src/site/antora/antora.tmpl.yml

@@ -45,6 +45,7 @@ asciidoc:
     project-id: "log4j"
     java-target-version: "${maven.compiler.target}"
     java-compiler-version: "${minimalJavaBuildVersion}"
+    log4j-kubernetes-url: "https://github.com/fabric8io/kubernetes-client/blob/main/doc/KubernetesLog4j.md"
     logback-url: "https://logback.qos.ch"
     logging-services-url: "https://logging.apache.org"
     lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor"

src/site/antora/antora.yml

@@ -45,6 +45,7 @@ asciidoc:
     project-id: "log4j"
     java-target-version: "8"
     java-compiler-version: "[17,18)"
+    log4j-kubernetes-url: "https://github.com/fabric8io/kubernetes-client/blob/main/doc/KubernetesLog4j.md"
     logback-url: "https://logback.qos.ch"
     logging-services-url: "https://logging.apache.org"
     lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor"

src/site/antora/modules/ROOT/examples/cloud/logstash/log4j2.json

@@ -0,0 +1,24 @@
+{
+  "Configuration": {
+    "Appenders": {
+      // tag::socketAppender[]
+      "Socket": {
+        "name": "SOCKET",
+        "host": "localhost",
+        "port": 12345,
+        "JsonTemplateLayout": {
+          "nullEventDelimiterEnabled": true
+        }
+      }
+      // end::socketAppender[]
+    },
+    "Loggers": {
+      "Root": {
+        "level": "WARN",
+        "AppenderRef": {
+          "ref": "SOCKET"
+        }
+      }
+    }
+  }
+}

src/site/antora/modules/ROOT/examples/cloud/logstash/log4j2.properties

@@ -0,0 +1,28 @@
+#
+# 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::socketAppender[]
+appender.0.type = Socket
+appender.0.name = SOCKET
+appender.0.host = localhost
+appender.0.port = 12345
+appender.0.layout.type = JsonTemplateLayout
+appender.0.layout.nullEventDelimiterEnabled = true
+# end::socketAppender[]
+
+rootLogger.level = WARN
+rootLogger.appenderRef.0.ref = SOCKET

src/site/antora/modules/ROOT/examples/cloud/logstash/log4j2.xml

@@ -0,0 +1,38 @@
+<?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::socketAppender[] -->
+    <Socket name="SOCKET" host="localhost" port="12345">
+      <JsonTemplateLayout nullEventDelimiterEnabled="true"/>
+    </Socket>
+    <!-- end::socketAppender[] -->
+  </Appenders>
+
+  <Loggers>
+    <Root level="WARN">
+      <AppenderRef ref="SOCKET"/>
+    </Root>
+  </Loggers>
+
+</Configuration>

src/site/antora/modules/ROOT/examples/cloud/logstash/log4j2.yaml

@@ -0,0 +1,33 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to you under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+Configuration:
+
+  Appenders:
+    # tag::socketAppender[]
+    Socket:
+      name: "SOCKET"
+      host: "localhost"
+      port: 12345
+      JsonTemplateLayout:
+        nullEventDelimiterEnabled: true
+    # end::socketAppender[]
+
+  Loggers:
+    Root:
+      level: "WARN"
+      AppenderRef:
+        ref: "SOCKET"

src/site/antora/modules/ROOT/pages/log4j-docker.adoc

@@ -15,31 +15,39 @@ Licensed to the Apache Software Foundation (ASF) under one or more
     limitations under the License.
 ////
 
-= Log4j Docker Support
-
-Log4j supports Docker by providing a Lookup to retrieve container information.
-
-== 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.
-
-== Lookup Attributes
-
-Log4j Docker provides access to the following container attributes:
-
-* containerId - The full id assigned to the container.
-* containerName - The name assigned to the container.
-* imageId - The id assigned to the image.
-* imageName - The name assigned to the image.
-* shortContainerId - The first 12 characters of the container id.
-* shortImageId - The first 12 characters of the image id.
-
-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.
+= Log4j Docker
+
+Log4j Docker module offers https://docker.com[Docker]-specific utilities.
+
+[#install]
+== Installation
+
+You need to add the following additional runtime dependency to your build to use Log4j Docker:
+
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<dependency>
+  <groupId>org.apache.logging.log4j</groupId>
+  <artifactId>log4j-docker</artifactId>
+  <version>{log4j-core-version}</version>
+  <scope>runtime</scope>
+</dependency>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+runtimeOnly 'org.apache.logging.log4j:log4j-docker:{log4j-core-version}'
+----
+====
+
+[#features]
+== Features
+
+Log4j Docker provides xref:manual/lookups.adoc#DockerLookup[Docker Lookup] that queries https://docs.docker.com/engine/api/[the API of the Docker Engine] running your container.
+You can use it to inject Docker-environment specific values (container ID, image name, etc.) in xref:manual/configuration.adoc#property-substitution[property substitutions].