src/site/xdoc/manual/logsep.xml - logging-log4j2 - Git at Google

 <?xml version="1.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.
 -->

 <document xmlns="http://maven.apache.org/XDOC/2.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
     <properties>
         <title>Logging Separation</title>
         <author email="rgoers@apache.org">Ralph Goers</author>
     </properties>

     <body>
       <section name="Logging Separation">
         <p>
           There are many well known use cases where applications may share an environment with other applications
           and each has a need to have its own, separate logging environment. This purpose of this section is to
           discuss some of these cases and ways to accomplish this.
         </p>
         <subsection name="Use Cases">
           <a name="UseCases"/>
           <p>
             This section describes some of the use cases where Log4j could be used and what its desired behavior
             might be.
           </p>
           <h4>Standalone Application</h4>
             <p>
               Standalone applications are usually relatively simple. They typically have one bundled executable
               that requires only a single logging configuration.
             </p>
           <h4>Web Applications</h4>
             <p>
               A typical web application will be packaged as a WAR file and will include all of its dependencies in
               WEB-INF/lib and will have its configuration file located in the class path or in a location
               configured in the web.xml. Be sure to follow the <a href="webapp.html">instructions to initialize Log4j 2
               in a web application</a>.
             </p>
           <h4>Java EE Applications</h4>
             <p>
               A Java EE application will consist of one or more WAR files and possible some EJBs, typically all
               packaged in an EAR file. Usually, it is desirable to have a single configuration that applies to
               all the components in the EAR. The logging classes will generally be placed in a location shared
               across all the components and the configuration needs to also be shareable.  Be sure to follow the
               <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>.
             </p>
           <h4>"Shared" Web Applications and REST Service Containers</h4>
             <p>
               In this scenario there are multiple WAR files deployed into a single container. Each of the applications
               should use the same logging configuration and share the same logging implementation across each of the
               web applications. When writing to files and streams each of the applications should share them to avoid
               the issues that can occur when multiple components try to write to the same file(s) through different
               File objects, channels, etc.
             </p>
           <h4>OSGi Applications</h4>
             <p>
               An OSGi container physically separates each JAR into its own ClassLoader, thus enforcing modularity of
               JARs as well as providing standardized ways for JARs to share code based on version numbers. Suffice to
               say, the OSGi framework is beyond the scope of this manual. There are some differences when using Log4j
               in an OSGi container. By default, each JAR bundle is scanned for its own Log4j configuration file.
               Similar to the web application paradigm, every bundle has its own LoggerContext. As this may be
               undesirable when a global Log4j configuration is wanted, then the
               <a href="extending.html#ContextSelector">ContextSelector</a> should be overridden with
               <code>BasicContextSelector</code> or <code>JndiContextSelector</code>.
             </p>
         </subsection>
         <subsection name="Approaches">
           <a name="Approaches"/>
           <h4>The Simple Approach</h4>
             <p>
               The simplest approach for separating logging within applications is to package each application with
               its own copy of Log4j and to use the BasicContextSelector. While this works for standalone applications
               and may work for web applications and possibly Java EE applications, it does not work at all in the
               last case.  However, when this approach does work it should be used as it is ultimately the simplest
               and most straightforward way of implementing logging.
             </p>

           <h4>Using Context Selectors</h4>
             <p>
               There are a few patterns for achieving the desired state of logging separation using ContextSelectors:
             </p>
               <ol>
                 <li>Place the logging jars in the container's classpath and set the system property
                   <tt>log4j2.contextSelector</tt> to <code>org.apache.logging.log4j.core.selector.BasicContextSelector</code>.
                   This will create a single LoggerContext using a single configuration that will be shared across all
                   applications.</li>
                 <li>
                   Place the logging jars in the container's classpath and use the default ClassLoaderContextSelector.
                   Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>. Each
                   application can be configured to share the same configuration used at the container or can be
                   individually configured. If status logging is set to debug in the configuration there will be output
                   from when logging is initialized in the container and then again in each web application.
                 </li>
                 <li>
                   Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a> and set
                   the system property or servlet context parameter <tt>log4j2.contextSelector</tt> to
                   <kbd>org.apache.logging.log4j.core.selector.JndiContextSelector</kbd>. This will cause the container
                   to use JNDI to locate each web application's <code>LoggerContext</code>. Be sure to set the
                   <code>isLog4jContextSelectorNamed</code> context parameter to <kbd>true</kbd> and also set the
                   <code>log4jContextName</code> and <code>log4jConfiguration</code> context parameters.
                 </li>
               </ol>
             <p>
               The exact method for setting system properties depends on the container. For Tomcat, edit
               <code>$CATALINA_HOME/conf/catalina.properties</code>. Consult the documentation for other web containers.
             </p>
         </subsection>
       </section>
     </body>
 </document>
	<?xml version="1.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.
	-->

	<document xmlns="http://maven.apache.org/XDOC/2.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
	<properties>
	<title>Logging Separation</title>
	<author email="rgoers@apache.org">Ralph Goers</author>
	</properties>

	<body>
	<section name="Logging Separation">
	<p>
	There are many well known use cases where applications may share an environment with other applications
	and each has a need to have its own, separate logging environment. This purpose of this section is to
	discuss some of these cases and ways to accomplish this.
	</p>
	<subsection name="Use Cases">
	<a name="UseCases"/>
	<p>
	This section describes some of the use cases where Log4j could be used and what its desired behavior
	might be.
	</p>
	<h4>Standalone Application</h4>
	<p>
	Standalone applications are usually relatively simple. They typically have one bundled executable
	that requires only a single logging configuration.
	</p>
	<h4>Web Applications</h4>
	<p>
	A typical web application will be packaged as a WAR file and will include all of its dependencies in
	WEB-INF/lib and will have its configuration file located in the class path or in a location
	configured in the web.xml. Be sure to follow the <a href="webapp.html">instructions to initialize Log4j 2
	in a web application</a>.
	</p>
	<h4>Java EE Applications</h4>
	<p>
	A Java EE application will consist of one or more WAR files and possible some EJBs, typically all
	packaged in an EAR file. Usually, it is desirable to have a single configuration that applies to
	all the components in the EAR. The logging classes will generally be placed in a location shared
	across all the components and the configuration needs to also be shareable. Be sure to follow the
	<a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>.
	</p>
	<h4>"Shared" Web Applications and REST Service Containers</h4>
	<p>
	In this scenario there are multiple WAR files deployed into a single container. Each of the applications
	should use the same logging configuration and share the same logging implementation across each of the
	web applications. When writing to files and streams each of the applications should share them to avoid
	the issues that can occur when multiple components try to write to the same file(s) through different
	File objects, channels, etc.
	</p>
	<h4>OSGi Applications</h4>
	<p>
	An OSGi container physically separates each JAR into its own ClassLoader, thus enforcing modularity of
	JARs as well as providing standardized ways for JARs to share code based on version numbers. Suffice to
	say, the OSGi framework is beyond the scope of this manual. There are some differences when using Log4j
	in an OSGi container. By default, each JAR bundle is scanned for its own Log4j configuration file.
	Similar to the web application paradigm, every bundle has its own LoggerContext. As this may be
	undesirable when a global Log4j configuration is wanted, then the
	<a href="extending.html#ContextSelector">ContextSelector</a> should be overridden with
	<code>BasicContextSelector</code> or <code>JndiContextSelector</code>.
	</p>
	</subsection>
	<subsection name="Approaches">
	<a name="Approaches"/>
	<h4>The Simple Approach</h4>
	<p>
	The simplest approach for separating logging within applications is to package each application with
	its own copy of Log4j and to use the BasicContextSelector. While this works for standalone applications
	and may work for web applications and possibly Java EE applications, it does not work at all in the
	last case. However, when this approach does work it should be used as it is ultimately the simplest
	and most straightforward way of implementing logging.
	</p>

	<h4>Using Context Selectors</h4>
	<p>
	There are a few patterns for achieving the desired state of logging separation using ContextSelectors:
	</p>
	<ol>
	<li>Place the logging jars in the container's classpath and set the system property
	<tt>log4j2.contextSelector</tt> to <code>org.apache.logging.log4j.core.selector.BasicContextSelector</code>.
	This will create a single LoggerContext using a single configuration that will be shared across all
	applications.</li>
	<li>
	Place the logging jars in the container's classpath and use the default ClassLoaderContextSelector.
	Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>. Each
	application can be configured to share the same configuration used at the container or can be
	individually configured. If status logging is set to debug in the configuration there will be output
	from when logging is initialized in the container and then again in each web application.
	</li>
	<li>
	Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a> and set
	the system property or servlet context parameter <tt>log4j2.contextSelector</tt> to
	<kbd>org.apache.logging.log4j.core.selector.JndiContextSelector</kbd>. This will cause the container
	to use JNDI to locate each web application's <code>LoggerContext</code>. Be sure to set the
	<code>isLog4jContextSelectorNamed</code> context parameter to <kbd>true</kbd> and also set the
	<code>log4jContextName</code> and <code>log4jConfiguration</code> context parameters.
	</li>
	</ol>
	<p>
	The exact method for setting system properties depends on the container. For Tomcat, edit
	<code>$CATALINA_HOME/conf/catalina.properties</code>. Consult the documentation for other web containers.
	</p>
	</subsection>
	</section>
	</body>
	</document>