This is an automated email from the ASF dual-hosted git repository. grobmeier pushed a commit to branch ms12_conversion_of_md_files in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 8e3312a00990f56bf701583bb2bbe5f296ad67bc Author: Christian Grobmeier <[email protected]> AuthorDate: Thu Feb 22 19:59:10 2024 +0100 migrated md.vm docs --- .../log4j-docker.adoc} | 47 +++-- .../log4j-flume-ng.adoc} | 69 ++++--- src/site/asciidoc/log4j-kubernetes.adoc | 201 +++++++++++++++++++++ .../log4j-mongodb4.adoc} | 28 +-- src/site/markdown/log4j-kubernetes.md.vm | 104 ----------- 5 files changed, 270 insertions(+), 179 deletions(-) diff --git a/src/site/markdown/log4j-docker.md.vm b/src/site/asciidoc/log4j-docker.adoc similarity index 59% rename from src/site/markdown/log4j-docker.md.vm rename to src/site/asciidoc/log4j-docker.adoc index 2dcb4e4c2a..78c7797415 100644 --- a/src/site/markdown/log4j-docker.md.vm +++ b/src/site/asciidoc/log4j-docker.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +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 @@ -14,24 +15,19 @@ 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. ---> -#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 -[Log4j Spring Cloud sample application](https://github.com/apache/logging-log4j-samples) -uses a socat proxy to access 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-log4j-samples[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: @@ -42,15 +38,16 @@ Log4j Docker provides access to the following container attributes: * shortContainerId - The first 12 characters of the container id. * shortImageId - The first 12 characters of the image id. -#set( $D = '${' ) -#set( $container = 'docker:containerId}') Attributes may be accessed by adding -``` -$D$container -``` -to the configuration. Note that docker variables are only resolved once during logging initializaton so they -shouldn't be referenced with more than one '$' character. -$h2 Requirements +---- +${docker:containerId} +---- + +to the configuration. +Note that docker variables are only resolved once during logging initializaton so they shouldn't be referenced with more than one '$' character. + +== Requirements + Log4j Docker requires Log4j Core, Log4j API and a minimum of Java 8. -For more information, see [Runtime Dependencies](runtime-dependencies.html). +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. diff --git a/src/site/markdown/log4j-flume-ng.md.vm b/src/site/asciidoc/log4j-flume-ng.adoc similarity index 82% rename from src/site/markdown/log4j-flume-ng.md.vm rename to src/site/asciidoc/log4j-flume-ng.adoc index 1a775789d7..1ecd2d82af 100644 --- a/src/site/markdown/log4j-flume-ng.md.vm +++ b/src/site/asciidoc/log4j-flume-ng.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +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 @@ -14,27 +15,23 @@ 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. ---> -#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. +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. +The persistent agent uses Berkeley DB. +The following dependency should be added to your pom.xml in addition to the log4j-flume-ng dependency. -<!-- TODO: use variables for dependency versions --> -``` +// TODO: use variables for dependency versions + +---- <dependencyManagement> <dependencies> <dependency> @@ -58,14 +55,13 @@ in addition to the log4j-flume-ng dependency. <layout>default</layout> </repository> </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. +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. -``` +---- <project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> <modelVersion>4.0.0</modelVersion> @@ -86,57 +82,57 @@ Flume Embedded Appender into an application. <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> - <version>${dollar}{slf4j.version}</version> + <version>${slf4j.version}</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-ext</artifactId> - <version>${dollar}{slf4j.version}</version> + <version>${slf4j.version}</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> - <version>${dollar}{log4j.version}</version> + <version>${log4j.version}</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-1.2-api</artifactId> - <version>${dollar}{log4j.version}</version> + <version>${log4j.version}</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> - <version>${dollar}{log4j.version}</version> + <version>${log4j.version}</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-flume-ng</artifactId> - <version>${dollar}{log4j.version}</version> + <version>${log4j.version}</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-slf4j-impl</artifactId> - <version>${dollar}{log4j.version}</version> + <version>${log4j.version}</version> </dependency> <dependency> <groupId>org.codehaus.jackson</groupId> <artifactId>jackson-core-asl</artifactId> - <version>${dollar}{jackson.version}</version> + <version>${jackson.version}</version> </dependency> <dependency> <groupId>org.codehaus.jackson</groupId> <artifactId>jackson-mapper-asl</artifactId> - <version>${dollar}{jackson.version}</version> + <version>${jackson.version}</version> </dependency> <dependency> <groupId>org.codehaus.jackson</groupId> <artifactId>jackson-jaxrs</artifactId> - <version>${dollar}{jackson.version}</version> + <version>${jackson.version}</version> </dependency> <dependency> <groupId>org.codehaus.jackson</groupId> <artifactId>jackson-xc</artifactId> - <version>${dollar}{jackson.version}</version> + <version>${jackson.version}</version> </dependency> </dependencies> </dependencyManagement> @@ -216,8 +212,9 @@ Flume Embedded Appender into an application. </dependency> </dependencies> </project> -``` +---- + +== Requirements -$h2 Requirements The Flume Appender requires the Log4J 2 API. -For more information, see [Runtime Dependencies](runtime-dependencies.html). +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. diff --git a/src/site/asciidoc/log4j-kubernetes.adoc b/src/site/asciidoc/log4j-kubernetes.adoc new file mode 100644 index 0000000000..46db935b4e --- /dev/null +++ b/src/site/asciidoc/log4j-kubernetes.adoc @@ -0,0 +1,201 @@ +// vim: set syn=markdown : + +//// +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. +//// += Log4j Kubernetes Support + +Log4j supports Kubernetes by providing a Lookup to retrieve container information. + +== 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. + +== Lookup Attributes + +Log4j Kubernetes provides access to the following container attributes: + +* accountName - The service account name. +* clusterName - The name of the cluster the application is running in. +* containerId - The full id assigned to the container. +* containerName - The name assigned to the container. +* host - The name of the host. +* hostIp - The host's ip address. +* imageId - The id assigned to the image. +* imageName - The name assigned to the image. +* labels - All labels formatted in a list. +* labels.app - The application name. +* labels.podTemplateHash - The pod's template hash value. +* masterUrl - The url needed to access the API server. +* namespaceId - The id of the namespace the various kubernetes components are located within. +* namespaceName - The namespace the various kubernetes components are located within. +* podId - The pod's id number. +* podIp - The pod's ip address. +* podName - The name of the pod. + +Attributes may be accessed by adding + +---- +${k8s:containerId} +---- + +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. + +== 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. +The properties below may either be configured using the Log4j variable names and located by Log4j's normal property resolution mechansim or Log4j will resolve the spring properties when the application is running in Spring Boot and the Spring Environment has been created. +Note that Spring Boot initializes logging 3 times and only the last will have a Spring Environment present. + +[cols=",>,>,>"] +|=== +| Log4j Property Name | Spring Property Name | Default | Description + +| log4j2.kubernetes.client.apiVersion +| spring.cloud.kubernetes.client.apiVersion +| v1 +| Kubernetes API Version + +| log4j2.kubernetes.client.caCertData +| spring.cloud.kubernetes.client.caCertData +| +| Kubernetes API CACertData + +| log4j2.kubernetes.client.caCertFile +| spring.cloud.kubernetes.client.caCertFile +| +| Kubernetes API CACertFile + +| log4j2.kubernetes.client.clientCertData +| spring.cloud.kubernetes.client.clientCertData +| +| Kubernetes API ClientCertData + +| log4j2.kubernetes.client.clientCertFile +| spring.cloud.kubernetes.client.clientCertFile +| +| Kubernetes API ClientCertFile + +| log4j2.kubernetes.client.clientKeyAlgo +| spring.cloud.kubernetes.client.clientKeyAlgo +| RSA +| Kubernetes API ClientKeyAlgo + +| log4j2.kubernetes.client.clientKeyData +| spring.cloud.kubernetes.client.clientKeyData +| +| Kubernetes API ClientKeyData + +| log4j2.kubernetes.client.clientKeyFile +| spring.cloud.kubernetes.client.clientKeyFile +| +| Kubernetes API ClientKeyFile + +| log4j2.kubernetes.client.clientKeyPassPhrase +| spring.cloud.kubernetes.client.clientKeyPassphrase +| changeit +| Kubernetes API ClientKeyPassphrase + +| log4j2.kubernetes.client.connectionTimeout +| spring.cloud.kubernetes.client.connectionTimeout +| 10s +| Connection timeout + +| log4j2.kubernetes.client.httpProxy +| spring.cloud.kubernetes.client.http-proxy +| +| + +| log4j2.kubernetes.client.httpsProxy +| spring.cloud.kubernetes.client.https-proxy +| +| + +| log4j2.kubernetes.client.loggingInberval +| spring.cloud.kubernetes.client.loggingInterval +| 20s +| Logging interval + +| log4j2.kubernetes.client.masterUrl +| spring.cloud.kubernetes.client.masterUrl +| kubernetes.default.svc +| Kubernetes API Master Node URL + +| log4j2.kubernetes.client.namespacce +| spring.cloud.kubernetes.client.namespace +| default +| Kubernetes Namespace + +| log4j2.kubernetes.client.noProxy +| spring.cloud.kubernetes.client.noProxy +| +| + +| log4j2.kubernetes.client.password +| spring.cloud.kubernetes.client.password +| +| Kubernetes API Password + +| log4j2.kubernetes.client.proxyPassword +| spring.cloud.kubernetes.client.proxyPassword +| +| + +| log4j2.kubernetes.client.proxyUsername +| spring.cloud.kubernetes.client.proxyUsername +| +| + +| log4j2.kubernetes.client.requestTimeout +| spring.cloud.kubernetes.client.requestTimeout +| 10s +| Request timeout + +| log4j2.kubernetes.client.rollingTimeout +| spring.cloud.kubernetes.client.rollingTimeout +| 900s +| Rolling timeout + +| log4j2.kubernetes.client.trustCerts +| spring.cloud.kubernetes.client.trustCerts +| false +| Kubernetes API Trust Certificates + +| log4j2.kubernetes.client.username +| spring.cloud.kubernetes.client.username +| +| Kubernetes API Username + +| log4j2.kubernetes.client.watchReconnectInterval +| spring.cloud.kubernetes.client.watchReconnectInterval +| 1s +| Reconnect Interval + +| log4j2.kubernetes.client.watchReconnectLimit +| spring.cloud.kubernetes.client.watchReconnectLimit +| -1 +| Reconnect Interval limit retries +|=== + +== 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/markdown/log4j-mongodb4.md.vm b/src/site/asciidoc/log4j-mongodb4.adoc similarity index 72% rename from src/site/markdown/log4j-mongodb4.md.vm rename to src/site/asciidoc/log4j-mongodb4.adoc index c246536836..c0f07f2c5d 100644 --- a/src/site/markdown/log4j-mongodb4.md.vm +++ b/src/site/asciidoc/log4j-mongodb4.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +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 @@ -14,17 +15,16 @@ 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. ---> -#set($h1='#') -#set($h2='##') -## TODO: use properties for dynamic dependency versions +//// + +// TODO: use properties for dynamic dependency versions -$h1 MongoDB appender += MongoDB appender -[MongoDB](http://www.mongodb.org/) is supported through the -[Java MongoDB Driver](http://docs.mongodb.org/ecosystem/drivers/java/). +http://www.mongodb.org/[MongoDB] is supported through the http://docs.mongodb.org/ecosystem/drivers/java/[Java MongoDB Driver]. -``` +[source, xml] +---- <dependencyManagement> <dependencies> <dependency> @@ -40,9 +40,9 @@ $h1 MongoDB appender <artifactId>mongo-java-driver</artifactId> </dependency> </dependencies> -``` +---- -$h2 Requirements +== Requirements The MongoDB Appender is dependent on the Log4j 2 API and implementation. -For more information, see [Runtime Dependencies](runtime-dependencies.html). +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. diff --git a/src/site/markdown/log4j-kubernetes.md.vm b/src/site/markdown/log4j-kubernetes.md.vm deleted file mode 100644 index 12b28f3374..0000000000 --- a/src/site/markdown/log4j-kubernetes.md.vm +++ /dev/null @@ -1,104 +0,0 @@ -<!-- vim: set syn=markdown : --> -<!-- - 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. ---> -#set($dollar = '$') -#set($h1='#') -#set($h2='##') - -$h1 Log4j Kubernetes Support - -Log4j supports Kubernetes by providing a Lookup to retrieve container information. - -$h2 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 - -Log4j Kubernetes provides access to the following container attributes: - -* accountName - The service account name. -* clusterName - The name of the cluster the application is running in. -* containerId - The full id assigned to the container. -* containerName - The name assigned to the container. -* host - The name of the host. -* hostIp - The host's ip address. -* imageId - The id assigned to the image. -* imageName - The name assigned to the image. -* labels - All labels formatted in a list. -* labels.app - The application name. -* labels.podTemplateHash - The pod's template hash value. -* masterUrl - The url needed to access the API server. -* namespaceId - The id of the namespace the various kubernetes components are located within. -* namespaceName - The namespace the various kubernetes components are located within. -* podId - The pod's id number. -* podIp - The pod's ip address. -* podName - The name of the pod. - -#set( $D = '${' ) -#set( $container = 'k8s:containerId}') -Attributes may be accessed by adding -``` -$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 - -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. The properties below may either be configured using the Log4j -variable names and located by Log4j's normal property resolution mechansim or Log4j will resolve the -spring properties when the application is running in Spring Boot and the Spring Environment has been created. -Note that Spring Boot initializes logging 3 times and only the last will have a Spring Environment present. - -| Log4j Property Name | Spring Property Name | Default | Description | -|------------------------ |----------------------:|----------:|------------:| -| log4j2.kubernetes.client.apiVersion | spring.cloud.kubernetes.client.apiVersion | v1 | Kubernetes API Version | -| log4j2.kubernetes.client.caCertData | spring.cloud.kubernetes.client.caCertData | | Kubernetes API CACertData | -| log4j2.kubernetes.client.caCertFile | spring.cloud.kubernetes.client.caCertFile | | Kubernetes API CACertFile | -| log4j2.kubernetes.client.clientCertData | spring.cloud.kubernetes.client.clientCertData | | Kubernetes API ClientCertData | -| log4j2.kubernetes.client.clientCertFile | spring.cloud.kubernetes.client.clientCertFile | | Kubernetes API ClientCertFile | -| log4j2.kubernetes.client.clientKeyAlgo | spring.cloud.kubernetes.client.clientKeyAlgo | RSA | Kubernetes API ClientKeyAlgo | -| log4j2.kubernetes.client.clientKeyData | spring.cloud.kubernetes.client.clientKeyData | | Kubernetes API ClientKeyData | -| log4j2.kubernetes.client.clientKeyFile | spring.cloud.kubernetes.client.clientKeyFile | | Kubernetes API ClientKeyFile | -| log4j2.kubernetes.client.clientKeyPassPhrase | spring.cloud.kubernetes.client.clientKeyPassphrase | changeit | Kubernetes API ClientKeyPassphrase | -| log4j2.kubernetes.client.connectionTimeout | spring.cloud.kubernetes.client.connectionTimeout | 10s | Connection timeout | -| log4j2.kubernetes.client.httpProxy | spring.cloud.kubernetes.client.http-proxy | | | -| log4j2.kubernetes.client.httpsProxy | spring.cloud.kubernetes.client.https-proxy | | | -| log4j2.kubernetes.client.loggingInberval | spring.cloud.kubernetes.client.loggingInterval | 20s | Logging interval | -| log4j2.kubernetes.client.masterUrl | spring.cloud.kubernetes.client.masterUrl | kubernetes.default.svc | Kubernetes API Master Node URL | -| log4j2.kubernetes.client.namespacce | spring.cloud.kubernetes.client.namespace | default | Kubernetes Namespace | -| log4j2.kubernetes.client.noProxy | spring.cloud.kubernetes.client.noProxy | | | -| log4j2.kubernetes.client.password | spring.cloud.kubernetes.client.password | | Kubernetes API Password | -| log4j2.kubernetes.client.proxyPassword | spring.cloud.kubernetes.client.proxyPassword | | | -| log4j2.kubernetes.client.proxyUsername | spring.cloud.kubernetes.client.proxyUsername | | | -| log4j2.kubernetes.client.requestTimeout | spring.cloud.kubernetes.client.requestTimeout | 10s | Request timeout | -| log4j2.kubernetes.client.rollingTimeout | spring.cloud.kubernetes.client.rollingTimeout | 900s | Rolling timeout | -| log4j2.kubernetes.client.trustCerts | spring.cloud.kubernetes.client.trustCerts | false | Kubernetes API Trust Certificates | -| log4j2.kubernetes.client.username | spring.cloud.kubernetes.client.username | | Kubernetes API Username | -| log4j2.kubernetes.client.watchReconnectInterval | spring.cloud.kubernetes.client.watchReconnectInterval | 1s | Reconnect Interval | -| log4j2.kubernetes.client.watchReconnectLimit | spring.cloud.kubernetes.client.watchReconnectLimit | -1 | Reconnect Interval limit retries | - -$h2 Requirements -Log4j Kubernetes requires Log4j Core, Log4j API and a minimum of Java 8. -For more information, see [Runtime Dependencies](runtime-dependencies.html).
