Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / fd5ee81fec460cbe9ad65f300b0faf1bf03c19bc / . / tomcat-cas / webapps / docs / logging.html
blob: 47eb81f8cc28c3a5f6b27045a99bf7172087d9c9 [file] [log] [blame]
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 (6.0.39) - Logging in Tomcat</title><meta name="author" content="Allistair Crossley"><meta name="author" content="Yoav Shapira"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
5 The Apache Tomcat Servlet/JSP Container
6 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.39, Jan 27 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tomcat 6.0</h1><h2>Logging in Tomcat</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
7<ul><li><a href="#Introduction">Introduction</a><ol><li><a href="#Java_logging_API_%E2%80%94_java.util.logging">Java logging API &mdash; java.util.logging</a></li><li><a href="#Servlets_logging_API">Servlets logging API</a></li><li><a href="#Console">Console</a></li><li><a href="#Access_logging">Access logging</a></li></ol></li><li><a href="#Using_java.util.logging_(default)">Using java.util.logging (default)</a><ol><li><a href="#Documentation_references">Documentation references</a></li><li><a href="#Considerations_for_productive_usage">Considerations for productive usage</a></li></ol></li><li><a href="#Using_Log4j">Using Log4j</a></li></ul>
8</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
9 <p>
10 Logging in Apache Tomcat is implemented with the help of
11 <a href="http://commons.apache.org/logging">Apache Commons Logging</a>
12 library. That library is a thin wrapper above different logging
13 frameworks. It provides Tomcat with the ability to log
14 hierarchically across various log levels without the need to rely on a
15 particular logging implementation.
16 </p>
17
18 <p>
19 Since Tomcat 6.0, Tomcat uses a private package-renamed implementation of
20 Apache Commons Logging, to allow web applications to use their own
21 independent copies of the original Apache Commons Logging library.
22 In the default distribution this private copy of the library
23 is simplified and hardcoded to use the <code>java.util.logging</code> framework.
24 </p>
25
26 <p>
27 To configure Tomcat to use alternative logging frameworks for its internal
28 logging, one has to replace the logging library with the one that is built
29 with the full implementation. Such library is provided as an <a href="extras.html">extras</a>
30 component. Instructions on how to configure Tomcat to use Log4j framework
31 for its internal logging may be found below.
32 </p>
33
34 <p>
35 A web application running on Apache Tomcat can:
36 </p>
37 <ul>
38 <li>
39 Use system logging API, <code>java.util.logging</code>.
40 </li>
41 <li>
42 Use logging API provided by the Java Servlets specification,
43 <code>javax.servlet.ServletContext.log(...)</code>
44 </li>
45 <li>
46 Use any logging framework of its choice.
47 </li>
48 </ul>
49
50 <p>
51 The logging frameworks used by different web applications run independently
52 of each other. See <a href="class-loader-howto.html">class loading</a>
53 for more details.
54 The exception to this rule is <code>java.util.logging</code>, if it used
55 directly or indirectly by your logging library. That is because it is loaded
56 by the system and is shared across web applications.
57 </p>
58
59 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Java logging API %E2%80%94 java.util.logging"><!--()--></a><a name="Java_logging_API_%E2%80%94_java.util.logging"><strong>Java logging API &mdash; java.util.logging</strong></a></font></td></tr><tr><td><blockquote>
60
61 <p>
62 Apache Tomcat has its own implementation of several key elements of
63 <code>java.util.logging</code> API. This implementation is called "JULI".
64 The key component there is a custom LogManager implementation,
65 that is aware of different web applications running on Tomcat (and
66 their different class loaders). It supports private per-application
67 logging configurations. It is also notified by Tomcat when a web application
68 is unloaded from memory, so that the references to its classes can be
69 cleared, preventing memory leaks.
70 </p>
71
72 <p>
73 This <code>java.util.logging</code> implementation is enabled by providing
74 certain system properties when starting Java. The Apache Tomcat startup
75 scripts do this for you, but if you are using different tools to run
76 Tomcat (such as jsvc, or running Tomcat from within an IDE), you should
77 take care of them by yourself.
78 </p>
79
80 <p>
81 More details about java.util.logging may be found in the documentation
82 for your JDK and on its Javadoc pages for the <code>java.util.logging</code>
83 package.
84 </p>
85
86 <p>
87 More details about Tomcat JULI may be found below.
88 </p>
89
90 </blockquote></td></tr></table>
91
92 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Servlets logging API"><!--()--></a><a name="Servlets_logging_API"><strong>Servlets logging API</strong></a></font></td></tr><tr><td><blockquote>
93
94 <p>
95 The calls to <code>javax.servlet.ServletContext.log(...)</code> to write
96 log messages are handled by internal Tomcat logging. Such messages are
97 logged to the category named
98 </p>
99 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>org.apache.catalina.core.ContainerBase.[${engine}].[${host}].[${context}]</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
100 <p>
101 This logging is performed according to the Tomcat logging configuration. You
102 cannot overwrite it in a web application.
103 </p>
104
105 <p>
106 The Servlets logging API predates the <code>java.util.logging</code> API
107 that is now provided by Java. As such, it does not offer you much options.
108 E.g., you cannot control the log levels. It can be noted, though, that
109 in Apache Tomcat implementation the calls to <code>ServletContext.log(String)</code>
110 or <code>GenericServlet.log(String)</code> are logged at the INFO level.
111 The calls to <code>ServletContext.log(String, Throwable)</code> or
112 <code>GenericServlet.log(String, Throwable)</code>
113 are logged at the ERROR level.
114 </p>
115
116 </blockquote></td></tr></table>
117
118 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Console"><strong>Console</strong></a></font></td></tr><tr><td><blockquote>
119
120 <p>
121 When running Tomcat on unixes, the console output is usually redirected
122 to the file named <code>catalina.out</code>. The name is configurable
123 using an environment variable. (See the startup scripts).
124 Whatever is written to <code>System.err/out</code> will be caught into
125 that file. That may include:
126 </p>
127
128 <ul>
129 <li>Uncaught exceptions printed by <code>java.lang.ThreadGroup.uncaughtException(..)</code></li>
130 <li>Thread dumps, if you requested them via a system signal</li>
131 </ul>
132
133 <p>
134 When running as a service on Windows, the console output is also caught
135 and redirected, but the file names are different.
136 </p>
137
138 <p>
139 The default logging configuration in Apache Tomcat writes the same
140 messages to the console and to a log file. This is great when using
141 Tomcat for development, but usually is not needed in production.
142 </p>
143
144 <p>
145 Old applications that still use <code>System.out</code> or <code>System.err</code>
146 can be tricked by setting <code>swallowOutput</code> attribute on a
147 <a href="config/context.html">Context</a>. If the attribute is set to
148 <code>true</code>, the calls to <code>System.out/err</code> during request
149 processing will be intercepted, and their output will be fed to the
150 logging subsystem using the
151 <code>javax.servlet.ServletContext.log(...)</code> calls.<br>
152 <strong>Note</strong>, that the <code>swallowOutput</code> feature is
153 actually a trick, and it has its limitations.
154 It works only with direct calls to <code>System.out/err</code>,
155 and only during request processing cycle. It may not work in other
156 threads that might be created by the application. It cannot be used to
157 intercept logging frameworks that themselves write to the system streams,
158 as those start early and may obtain a direct reference to the streams
159 before the redirection takes place.
160 </p>
161
162 </blockquote></td></tr></table>
163
164 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Access logging"><!--()--></a><a name="Access_logging"><strong>Access logging</strong></a></font></td></tr><tr><td><blockquote>
165
166 <p>
167 A related, but different feature is access logging. It can be configured
168 as a valve at the Context, or Host, or Engine. See <a href="config/valve.html">Valves</a>
169 documentation for more details.
170 </p>
171
172 </blockquote></td></tr></table>
173
174 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Using java.util.logging (default)"><!--()--></a><a name="Using_java.util.logging_(default)"><strong>Using java.util.logging (default)</strong></a></font></td></tr><tr><td><blockquote>
175
176 <p>
177 The default implementation of java.util.logging provided in the JDK is too
178 limited to be useful. A limitation of JDK Logging appears to be the
179 inability to have per-web application logging, as the configuration is
180 per-VM. As a result, Tomcat will, in the default configuration, replace the
181 default LogManager implementation with a container friendly implementation
182 called JULI, which addresses these shortcomings. It supports the same
183 configuration mechanisms as the standard JDK java.util.logging, using either
184 a programmatic approach, or properties files. The main difference is that
185 per-classloader properties files can be set (which enables easy redeployment
186 friendly webapp configuration), and the properties files support slightly
187 extended constructs which allows more freedom for defining handlers and
188 assigning them to loggers.
189 </p>
190 <p>
191 JULI is enabled by default, and supports per classloader configuration, in
192 addition to the regular global java.util.logging configuration. This means
193 that logging can be configured at the following layers:
194 <ul>
195 <li>Globally. That is usually done in the
196 <code>${catalina.base}/conf/logging.properties</code> file.
197 The file is specified by the <code>java.util.logging.config.file</code>
198 System property which is set by the startup scripts.
199 If it is not readable or is not configured, the default is to use the
200 <code>${java.home}/lib/logging.properties</code> file in the JRE.
201 </li>
202 <li>In the web application. The file will be
203 <code>WEB-INF/classes/logging.properties</code>
204 </li>
205 </ul>
206 </p>
207 <p>
208 The default <code>logging.properties</code> in the JRE specifies a
209 <code>ConsoleHandler</code> that routes logging to System.err.
210 The default <code>conf/logging.properties</code> in Apache Tomcat also
211 adds several <code>FileHandler</code>s that write to files.
212 </p>
213 <p>
214 A handler's log level threshold is INFO by default and can be set using
215 SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST or ALL.
216 You can also target specific packages to collect logging from and specify
217 a level.
218 </p>
219 <p>
220 Here is how you would set debugging from Tomcat. You would need to ensure the
221 ConsoleHandler's (or FileHandler's') level is also set to collect this threshold,
222 so FINEST or ALL should be set. Please refer to <code>java.util.logging</code>
223 documentation in the JDK for the complete details:
224 </p>
225 <p>
226 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>org.apache.catalina.level=FINEST</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
227 </p>
228 <p>
229 The configuration used by JULI is extremely similar to the one supported by
230 plain <code>java.util.logging</code>, but uses a few
231 extensions to allow better flexibility in assigning loggers. The main
232 differences are:
233 </p>
234 <ul>
235 <li>A prefix may be added to handler names, so that multiple handlers of a
236 single class may be instantiated. A prefix is a String which starts with a
237 digit, and ends with '.'. For example, <code>22foobar.</code> is a valid
238 prefix.</li>
239 <li>System property replacement is performed for property values which
240 contain ${systemPropertyName}.</li>
241 <li>As in Java 6.0, loggers can define a list of handlers using the
242 <code>loggerName.handlers</code> property.</li>
243 <li>By default, loggers will not delegate to their parent if they have
244 associated handlers. This may be changed per logger using the
245 <code>loggerName.useParentHandlers</code> property, which accepts a
246 boolean value.</li>
247 <li>The root logger can define its set of handlers using the
248 <code>.handlers</code> property.</li>
249 </ul>
250 <p>
251 There are several additional implementation classes, that can be used
252 together with the ones provided by Java. The notable one is
253 <code>org.apache.juli.FileHandler</code>.
254 </p>
255 <p>
256 <code>org.apache.juli.FileHandler</code> supports buffering of the
257 logs. The buffering is not enabled by default. To configure it, use the
258 <code>bufferSize</code> property of a handler. A value of <code>0</code>
259 uses system default buffering (typically an 8K buffer will be used). A
260 value of <code>&lt;0</code> forces a writer flush upon each log write. A
261 value <code>&gt;0</code> uses a BufferedOutputStream with the defined
262 value but note that the system default buffering will also be
263 applied.
264 </p>
265 <p>
266 Example logging.properties file to be placed in $CATALINA_BASE/conf:
267 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
268handlers = 1catalina.org.apache.juli.FileHandler, \
269 2localhost.org.apache.juli.FileHandler, \
270 3manager.org.apache.juli.FileHandler, \
271 java.util.logging.ConsoleHandler
272
273.handlers = 1catalina.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
274
275############################################################
276# Handler specific properties.
277# Describes specific configuration info for Handlers.
278############################################################
279
2801catalina.org.apache.juli.FileHandler.level = FINE
2811catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
2821catalina.org.apache.juli.FileHandler.prefix = catalina.
283
2842localhost.org.apache.juli.FileHandler.level = FINE
2852localhost.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
2862localhost.org.apache.juli.FileHandler.prefix = localhost.
287
2883manager.org.apache.juli.FileHandler.level = FINE
2893manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
2903manager.org.apache.juli.FileHandler.prefix = manager.
2913manager.org.apache.juli.FileHandler.bufferSize = 16384
292
293java.util.logging.ConsoleHandler.level = FINE
294java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
295
296
297############################################################
298# Facility specific properties.
299# Provides extra control for each logger.
300############################################################
301
302org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO
303org.apache.catalina.core.ContainerBase.[Catalina].[localhost].handlers = \
304 2localhost.org.apache.juli.FileHandler
305
306org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].level = INFO
307org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].handlers = \
308 3manager.org.apache.juli.FileHandler
309
310# For example, to log debug messages in ContextConfig and HostConfig
311# classes and to log only warnings and errors in other
312# org.apache.catalina.** classes, uncomment these lines:
313#org.apache.catalina.startup.ContextConfig.level = FINE
314#org.apache.catalina.startup.HostConfig.level = FINE
315#org.apache.catalina.level = WARNING
316</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
317 </p>
318
319 <p>
320 Example logging.properties for the servlet-examples web application to be
321 placed in WEB-INF/classes inside the web application:
322 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
323handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
324
325############################################################
326# Handler specific properties.
327# Describes specific configuration info for Handlers.
328############################################################
329
330org.apache.juli.FileHandler.level = FINE
331org.apache.juli.FileHandler.directory = ${catalina.base}/logs
332org.apache.juli.FileHandler.prefix = servlet-examples.
333
334java.util.logging.ConsoleHandler.level = FINE
335java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
336</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
337 </p>
338
339 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Documentation references"><!--()--></a><a name="Documentation_references"><strong>Documentation references</strong></a></font></td></tr><tr><td><blockquote>
340 <p>See the following resources for additional information:</p>
341 <ul>
342 <li>Apache Tomcat Javadoc for the
343 <a href="api/org/apache/juli/package-summary.html"><code>org.apache.juli</code></a>
344 package.
345 </li>
346 <li>Oracle Java 6 Javadoc for the
347 <a href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html"><code>java.util.logging</code></a>
348 package.
349 </li>
350 </ul>
351 </blockquote></td></tr></table>
352
353 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Considerations for productive usage"><!--()--></a><a name="Considerations_for_productive_usage"><strong>Considerations for productive usage</strong></a></font></td></tr><tr><td><blockquote>
354 <p>You may want to take note of the following:</p>
355 <ul>
356 <li><p>Consider removing <code>ConsoleHandler</code> from configuration.</p>
357 <p>By default (thanks to the <code>.handlers</code> setting) logging goes
358 both to a <code>FileHandler</code> and to a <code>ConsoleHandler</code>.
359 The output of the latter one is usually captured into a file, such as
360 <code>catalina.out</code>. Thus you end up with two copies of the same
361 messages.</p>
362 </li>
363 <li><p>Consider removing <code>FileHandler</code>s for the applications
364 that you do not use. E.g., the one for <code>host-manager</code>.</p></li>
365 <li><p>The handlers by default use the system default encoding to write
366 the log files. It can be configured with <code>encoding</code> property.
367 See Javadoc for details.</p></li>
368 <li><p>Consider configuring an <a href="config/valve.html">Access
369 log</a>.</p></li>
370 </ul>
371 </blockquote></td></tr></table>
372
373 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Using Log4j"><!--()--></a><a name="Using_Log4j"><strong>Using Log4j</strong></a></font></td></tr><tr><td><blockquote>
374 <p>
375 This section explains how to configure Tomcat to use
376 <a href="http://logging.apache.org/log4j/">log4j</a> rather than
377 java.util.logging for all Tomcat's internal logging.
378 </p>
379 <p><em>Note</em>: The steps described in this section are needed
380 when you want to reconfigure Tomcat to use Apache log4j for its own
381 logging. These steps are <strong>not</strong> needed if you just want
382 to use log4j in your own web application. &mdash; In that case, just
383 put <code>log4j.jar</code> and <code>log4j.properties</code> into
384 <code>WEB-INF/lib</code> and <code>WEB-INF/classes</code>
385 of your web application.
386 </p>
387 <p>
388 The following steps describe configuring log4j to output Tomcat's
389 internal logging.
390 </p>
391
392 <ol>
393 <li>Create a file called <code>log4j.properties</code> with the
394 following content and save it into <code>$CATALINA_BASE/lib</code></li>
395 </ol>
396 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
397log4j.rootLogger=INFO, CATALINA
398
399# Define all the appenders
400log4j.appender.CATALINA=org.apache.log4j.DailyRollingFileAppender
401log4j.appender.CATALINA.File=${catalina.base}/logs/catalina.
402log4j.appender.CATALINA.Append=true
403log4j.appender.CATALINA.Encoding=UTF-8
404# Roll-over the log once per day
405log4j.appender.CATALINA.DatePattern='.'yyyy-MM-dd'.log'
406log4j.appender.CATALINA.layout = org.apache.log4j.PatternLayout
407log4j.appender.CATALINA.layout.ConversionPattern = %d [%t] %-5p %c- %m%n
408
409log4j.appender.LOCALHOST=org.apache.log4j.DailyRollingFileAppender
410log4j.appender.LOCALHOST.File=${catalina.base}/logs/localhost.
411log4j.appender.LOCALHOST.Append=true
412log4j.appender.LOCALHOST.Encoding=UTF-8
413log4j.appender.LOCALHOST.DatePattern='.'yyyy-MM-dd'.log'
414log4j.appender.LOCALHOST.layout = org.apache.log4j.PatternLayout
415log4j.appender.LOCALHOST.layout.ConversionPattern = %d [%t] %-5p %c- %m%n
416
417log4j.appender.MANAGER=org.apache.log4j.DailyRollingFileAppender
418log4j.appender.MANAGER.File=${catalina.base}/logs/manager.
419log4j.appender.MANAGER.Append=true
420log4j.appender.MANAGER.Encoding=UTF-8
421log4j.appender.MANAGER.DatePattern='.'yyyy-MM-dd'.log'
422log4j.appender.MANAGER.layout = org.apache.log4j.PatternLayout
423log4j.appender.MANAGER.layout.ConversionPattern = %d [%t] %-5p %c- %m%n
424
425log4j.appender.HOST-MANAGER=org.apache.log4j.DailyRollingFileAppender
426log4j.appender.HOST-MANAGER.File=${catalina.base}/logs/host-manager.
427log4j.appender.HOST-MANAGER.Append=true
428log4j.appender.HOST-MANAGER.Encoding=UTF-8
429log4j.appender.HOST-MANAGER.DatePattern='.'yyyy-MM-dd'.log'
430log4j.appender.HOST-MANAGER.layout = org.apache.log4j.PatternLayout
431log4j.appender.HOST-MANAGER.layout.ConversionPattern = %d [%t] %-5p %c- %m%n
432
433log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
434log4j.appender.CONSOLE.Encoding=UTF-8
435log4j.appender.CONSOLE.layout = org.apache.log4j.PatternLayout
436log4j.appender.CONSOLE.layout.ConversionPattern = %d [%t] %-5p %c- %m%n
437
438# Configure which loggers log to which appenders
439log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=INFO, LOCALHOST
440log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager]=\
441 INFO, MANAGER
442log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager]=\
443 INFO, HOST-MANAGER
444</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
445 <ol start="2">
446 <li><a href="http://logging.apache.org/log4j">Download Log4J</a>
447 (v1.2 or later).</li>
448
449 <li><p>Download or build <code>tomcat-juli.jar</code> and
450 <code>tomcat-juli-adapters.jar</code> that are available as an "extras"
451 component for Tomcat. See <a href="extras.html">Additional Components
452 documentation</a> for details.</p>
453 <p>This <code>tomcat-juli.jar</code> differs from the default one. It
454 contains the full Apache Commons Logging implementation and thus is
455 able to discover the presense of log4j and configure itself.</p>
456 </li>
457
458 <li><p>If you want to configure Tomcat to use log4j globally:</p>
459 <ul>
460 <li>Put <code>log4j.jar</code> and
461 <code>tomcat-juli-adapters.jar</code> from "extras" into
462 <code>$CATALINA_HOME/lib</code>.</li>
463 <li>Replace <code>$CATALINA_HOME/bin/tomcat-juli.jar</code> with
464 <code>tomcat-juli.jar</code> from "extras".</li>
465 </ul>
466 </li>
467
468 <li><p>If you are running Tomcat with separate $CATALINA_HOME and
469 $CATALINA_BASE and want to configure to use log4j in a single
470 $CATALINA_BASE only:</p>
471 <ul>
472 <li>Create <code>$CATALINA_BASE/bin</code> and
473 <code>$CATALINA_BASE/lib</code> directories if they do not exist.
474 </li>
475 <li>Put <code>log4j.jar</code> and
476 <code>tomcat-juli-adapters.jar</code> from "extras" into
477 <code>$CATALINA_BASE/lib</code></li>
478 <li>Put <code>tomcat-juli.jar</code> from "extras" as
479 <code>$CATALINA_BASE/bin/tomcat-juli.jar</code></li>
480 <li>If you are running with a
481 <a href="security-manager-howto.html">security manager</a>, you
482 would need to edit the
483 <code>$CATALINA_BASE/conf/catalina.policy</code> file to adjust
484 it to using a different copy of tomcat-juli.jar.</li>
485 <li>The old <code>tomcat-juli.jar</code> in
486 <code>$CATALINA_HOME/bin</code> is still referenced by manifest of
487 <code>bootstrap.jar</code> and thus will be implicitly present
488 on Tomcat's classpath. The startup scripts configure
489 <code>$CATALINA_BASE/bin/tomcat-juli.jar</code> to be earlier on the
490 classpath than <code>bootstrap.jar</code>, and so it should have
491 higher priority. Thus it should be OK, but
492 consider removing the unneeded copy of <code>tomcat-juli.jar</code>
493 (copy it into all other $CATALINA_BASEs that do not use log4j).
494 Tomcat 7 does not have this issue.</li>
495 </ul>
496 </li>
497
498 <li><p>Delete <code>$CATALINA_BASE/conf/logging.properties</code> to
499 prevent java.util.logging generating zero length log files.</p></li>
500
501 <li><p>Start Tomcat</p></li>
502 </ol>
503
504 <p>
505 This log4j configuration mirrors the default java.util.logging setup
506 that ships with Tomcat: both the manager and host-manager apps get an
507 individual log file, and everything else goes to the "catalina.log" log
508 file. Each file is rolled-over once per day.
509 </p>
510
511 <p>
512 You can (and should) be more picky about which packages to include
513 in the logging. Tomcat defines loggers by Engine and Host names.
514 For example, for a more detailed Catalina localhost log, add this to the
515 end of the log4j.properties above. Note that there are known issues with
516 using this naming convention (with square brackets) in log4j XML based
517 configuration files, so we recommend you use a properties file as
518 described until a future version of log4j allows this convention.
519 </p>
520 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
521log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG
522log4j.logger.org.apache.catalina.core=DEBUG
523log4j.logger.org.apache.catalina.session=DEBUG
524</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
525
526 <p>
527 Be warned: a level of DEBUG will produce megabytes of logging and slow
528 startup of Tomcat. This level should be used sparingly when debugging of
529 internal Tomcat operations is required.
530 </p>
531
532 <p>
533 Your web applications should certainly use their own log4j configuration.
534 This is valid <i>with</i> the above configuration. You would place a
535 similar log4j.properties file in your web application's WEB-INF/classes
536 directory, and log4jx.y.z.jar into WEB-INF/lib. Then specify your package
537 level logging. This is a basic setup of log4j which does *not* require
538 Commons-Logging, and you should consult the
539 <a href="http://logging.apache.org/log4j/docs/documentation.html">log4j
540 documentation</a> for more options. This page is intended only as a
541 bootstrapping guide.
542 </p>
543
544 <p><em>Additional notes</em></p>
545 <ul>
546 <li><p>This exposes log4j libraries to the web applications through the
547 Common classloader. See <a href="class-loader-howto.html">class loading</a>
548 documentation for details.</p>
549 <p>Because of that, the web applications and libraries using
550 <a href="http://commons.apache.org/logging">Apache Commons Logging</a>
551 library are likely to automatically choose log4j as the underlying
552 logging implementation.</p></li>
553
554 <li><p>The <code>java.util.logging</code> API is still available, for
555 those web applications that use it directly. The
556 <code>${catalina.base}/conf/logging.properties</code> file is still
557 referenced by Tomcat startup scripts.</p>
558 <p> Removal of <code>${catalina.base}/conf/logging.properties</code>
559 file, mentioned as one of the steps, just causes
560 <code>java.util.logging</code> to fallback to the default configuration
561 as configured in JRE, which is to use a ConsoleHandler and do not
562 create any files.</p></li>
563 </ul>
564 </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
565 Copyright &copy; 1999-2014, Apache Software Foundation
566 </em></font></div></td></tr></table></body></html>