"Fossies" - the Fresh Open Source Software Archive

Member "apache-log4j-2.12.4-src/src/site/xdoc/manual/logsep.xml" (20 Dec 2021, 7935 Bytes) of package /linux/misc/apache-log4j-2.12.4-src.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0"?>
    2 <!--
    3     Licensed to the Apache Software Foundation (ASF) under one or more
    4     contributor license agreements.  See the NOTICE file distributed with
    5     this work for additional information regarding copyright ownership.
    6     The ASF licenses this file to You under the Apache License, Version 2.0
    7     (the "License"); you may not use this file except in compliance with
    8     the License.  You may obtain a copy of the License at
   10          http://www.apache.org/licenses/LICENSE-2.0
   12     Unless required by applicable law or agreed to in writing, software
   13     distributed under the License is distributed on an "AS IS" BASIS,
   14     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   15     See the License for the specific language governing permissions and
   16     limitations under the License.
   17 -->
   19 <document xmlns="http://maven.apache.org/XDOC/2.0"
   20           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   21           xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
   22     <properties>
   23         <title>Logging Separation</title>
   24         <author email="rgoers@apache.org">Ralph Goers</author>
   25     </properties>
   27     <body>
   28       <section name="Logging Separation">
   29         <p>
   30           There are many well known use cases where applications may share an environment with other applications
   31           and each has a need to have its own, separate logging environment. This purpose of this section is to
   32           discuss some of these cases and ways to accomplish this.
   33         </p>
   34         <subsection name="Use Cases">
   35           <a name="UseCases"/>
   36           <p>
   37             This section describes some of the use cases where Log4j could be used and what its desired behavior
   38             might be.
   39           </p>
   40           <h4>Standalone Application</h4>
   41             <p>
   42               Standalone applications are usually relatively simple. They typically have one bundled executable
   43               that requires only a single logging configuration.
   44             </p>
   45           <h4>Web Applications</h4>
   46             <p>
   47               A typical web application will be packaged as a WAR file and will include all of its dependencies in
   48               WEB-INF/lib and will have its configuration file located in the class path or in a location
   49               configured in the web.xml. Be sure to follow the <a href="webapp.html">instructions to initialize Log4j 2
   50               in a web application</a>.
   51             </p>
   52           <h4>Java EE Applications</h4>
   53             <p>
   54               A Java EE application will consist of one or more WAR files and possible some EJBs, typically all
   55               packaged in an EAR file. Usually, it is desirable to have a single configuration that applies to
   56               all the components in the EAR. The logging classes will generally be placed in a location shared
   57               across all the components and the configuration needs to also be shareable.  Be sure to follow the
   58               <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>.
   59             </p>
   60           <h4>"Shared" Web Applications and REST Service Containers</h4>
   61             <p>
   62               In this scenario there are multiple WAR files deployed into a single container. Each of the applications
   63               should use the same logging configuration and share the same logging implementation across each of the
   64               web applications. When writing to files and streams each of the applications should share them to avoid
   65               the issues that can occur when multiple components try to write to the same file(s) through different
   66               File objects, channels, etc.
   67             </p>
   68           <h4>OSGi Applications</h4>
   69             <p>
   70               An OSGi container physically separates each JAR into its own ClassLoader, thus enforcing modularity of
   71               JARs as well as providing standardized ways for JARs to share code based on version numbers. Suffice to
   72               say, the OSGi framework is beyond the scope of this manual. There are some differences when using Log4j
   73               in an OSGi container. By default, each JAR bundle is scanned for its own Log4j configuration file.
   74               Similar to the web application paradigm, every bundle has its own LoggerContext. As this may be
   75               undesirable when a global Log4j configuration is wanted, then the
   76               <a href="extending.html#ContextSelector">ContextSelector</a> should be overridden with
   77               <code>BasicContextSelector</code> or <code>JndiContextSelector</code>.
   78             </p>
   79         </subsection>
   80         <subsection name="Approaches">
   81           <a name="Approaches"/>
   82           <h4>The Simple Approach</h4>
   83             <p>
   84               The simplest approach for separating logging within applications is to package each application with
   85               its own copy of Log4j and to use the BasicContextSelector. While this works for standalone applications
   86               and may work for web applications and possibly Java EE applications, it does not work at all in the
   87               last case.  However, when this approach does work it should be used as it is ultimately the simplest
   88               and most straightforward way of implementing logging.
   89             </p>
   91           <h4>Using Context Selectors</h4>
   92             <p>
   93               There are a few patterns for achieving the desired state of logging separation using ContextSelectors:
   94             </p>
   95               <ol>
   96                 <li>Place the logging jars in the container's classpath and set the system property
   97                   <tt>log4j2.contextSelector</tt> to <code>org.apache.logging.log4j.core.selector.BasicContextSelector</code>.
   98                   This will create a single LoggerContext using a single configuration that will be shared across all
   99                   applications.</li>
  100                 <li>
  101                   Place the logging jars in the container's classpath and use the default ClassLoaderContextSelector.
  102                   Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>. Each
  103                   application can be configured to share the same configuration used at the container or can be
  104                   individually configured. If status logging is set to debug in the configuration there will be output
  105                   from when logging is initialized in the container and then again in each web application.
  106                 </li>
  107                 <li>
  108                   Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a> and set
  109                   the system property or servlet context parameter <tt>log4j2.contextSelector</tt> to
  110                   <kbd>org.apache.logging.log4j.core.selector.JndiContextSelector</kbd>. This will cause the container
  111                   to use JNDI to locate each web application's <code>LoggerContext</code>. Be sure to set the
  112                   <code>isLog4jContextSelectorNamed</code> context parameter to <kbd>true</kbd> and also set the
  113                   <code>log4jContextName</code> and <code>log4jConfiguration</code> context parameters.
  114                   Note that the JndiContextSelector will not work unless <code>log4j2.enableJndiContextSelector=true</code> is set as a
  115                   system property or environment variable. See the
  116                   <a href="./configuration.html#enableJndiContextSelector">enableJndiContextSelector</a> system property.
  117                 </li>
  118               </ol>
  119             <p>
  120               The exact method for setting system properties depends on the container. For Tomcat, edit
  121               <code>$CATALINA_HOME/conf/catalina.properties</code>. Consult the documentation for other web containers.
  122             </p>
  123         </subsection>
  124       </section>
  125     </body>
  126 </document>