log4j-kubernetes/src/site/markdown/index.md.vm - logging-log4j2 - Git at Google

 <!-- 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).
	<!-- 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).