"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
9
10 http://www.apache.org/licenses/LICENSE-2.0
11
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 -->
18
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>
26
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>
90
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>