Bug 55215 - Improvements to sample log4j configuration
Improvements to sample log4j configuration
Status: RESOLVED FIXED
Product: Tomcat 8
Classification: Unclassified
Component: Documentation
trunk
PC Linux
: P2 minor (vote)
: ----
Assigned To: Tomcat Developers Mailing List
:
Depends on:
Blocks:
  Show dependency tree
 
Reported: 2013-07-08 17:58 UTC by Brian Burch
Modified: 2014-04-27 23:27 UTC (History)
0 users



Attachments
patch to docs/logging.xml (4.65 KB, patch)
2013-07-08 17:58 UTC, Brian Burch
Details | Diff
patch to clarify use of ${CATALINA_BASE}/bin (881 bytes, text/plain)
2013-07-11 08:48 UTC, Brian Burch
Details
clarify log4j and AccessLog issues (3.96 KB, text/plain)
2013-08-01 15:36 UTC, Brian Burch
Details
clarify log4j and AccessLog issues (2.66 KB, patch)
2013-08-01 15:38 UTC, Brian Burch
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Brian Burch 2013-07-08 17:58:14 UTC
Created attachment 30569 [details]
patch to docs/logging.xml

I decided to make a fresh start with my log4j configuration because it hasn't changed much since tc5. Naturally, I chose http://tomcat.apache.org/tomcat-7.0-doc/logging.html as my starting point.

The sample configuration seems to suffer from the same kind of problem - log4j was quite picky about syntax in "the old days" and so the current version seemd to be worth a spring clean.

1. The File properties cause the "live" log files to be created with names that have a trailing dot. Further, as these files are renamed by the Rolling Appender they end up with a double dot in the middle of the new file name.

2. The "live" files also acquire an additional ".log" suffix when Rolled. This is superfluous when the configuration quite sensibly puts all the files into a subdirectory called "logs".

3. Following log4j best practices (http://juliusdavies.ca/logging.html), I have extracted three error-prone substrings which are used many times, and defined them at the top of the configuration as local log4j symbolic variables.

4. I have consistently used white space around the property equals signs to improve readability. Some of the older properties did not use white space, while the newer ones did.

The patch is directed at tc8 trunk, although the generated html sample configuration is a subset of that currently working on my production tc7 system.
Comment 1 Konstantin Kolinko 2013-07-08 19:55:19 UTC
(In reply to Brian Burch from comment #0)
> Created attachment 30569 [details]
> patch to docs/logging.xml
> 
> I decided to make a fresh start with my log4j configuration because it
> hasn't changed much since tc5. Naturally, I chose
> http://tomcat.apache.org/tomcat-7.0-doc/logging.html as my starting point.
> 
> The sample configuration seems to suffer from the same kind of problem -
> log4j was quite picky about syntax in "the old days" and so the current
> version seemd to be worth a spring clean.
> 
> 1. The File properties cause the "live" log files to be created with names
> that have a trailing dot. Further, as these files are renamed by the Rolling
> Appender they end up with a double dot in the middle of the new file name.
> 

So it boils down to removing the trailing dot from
log4j.appender.CATALINA.File=${catalina.base}/logs/catalina.
to be
log4j.appender.CATALINA.File=${catalina.base}/logs/catalina

and so on, because the dot is already contained in DatePattern property.

> 2. The "live" files also acquire an additional ".log" suffix when Rolled.
> This is superfluous when the configuration quite sensibly puts all the files
> into a subdirectory called "logs".

I think this should be kept as is.

1). The .log suffix might be needed e.g. to assign mime types when serving those files through HTTP.

It may be also useful when transferring such files between systems. Some clients automatically do LF<->CRLF according to file types.

2). This configuration is supposed to match the default (JULI) one.

> 3. Following log4j best practices (http://juliusdavies.ca/logging.html), I
> have extracted three error-prone substrings which are used many times, and
> defined them at the top of the configuration as local log4j symbolic
> variables.

Interesting, but I suspect that it will be harder for newbies to read such configuration.
 
> 4. I have consistently used white space around the property equals signs to
> improve readability. Some of the older properties did not use white space,
> while the newer ones did.
> 
> The patch is directed at tc8 trunk, although the generated html sample
> configuration is a subset of that currently working on my production tc7
> system.
Comment 2 Mark Thomas 2013-07-10 11:54:19 UTC
Thanks for the patch.

I've applied changed 1 & 4 but not 2 & 3 for the reasons Konstantin outlined below.
Comment 3 Brian Burch 2013-07-11 08:45:58 UTC
When I was working through the install instructions, I was puzzled by the instruction to put the log4j version of tomcat-juli.jar into a directory called bin in ${CATALINA_BASE}. It took me a while to figure out. I checked catalina.properties and confirmed the path was not specified for the common.loader. I then found some relevant comments in class-loader-howto.html. When I looked at the logic in catalina.sh, all became clear.

I suppose a tomcat expert would know about this already, but it might not be so obvious to everyone else. My proposed change would help someone configuring global log4j to see why "/bin" is not a typo, understand something important and move on quickly with confidence.
Comment 4 Brian Burch 2013-07-11 08:48:01 UTC
Created attachment 30579 [details]
patch to clarify use of ${CATALINA_BASE}/bin
Comment 5 Mark Thomas 2013-07-11 15:28:11 UTC
Further clarificartion added but with different, expanded wording.
Comment 6 Brian Burch 2013-08-01 15:36:21 UTC
Created attachment 30657 [details]
clarify log4j and AccessLog issues

Following Konstantin's explanation of the design of AccessLog, I have linked the various sections of this page, clarified some phrases and added some new information. The intent is to assist readers coming at this subject from any of several directions to not overlook this important exception.
Comment 7 Brian Burch 2013-08-01 15:38:53 UTC
Created attachment 30658 [details]
clarify log4j and AccessLog issues
Comment 8 Brian Burch 2013-08-01 15:41:26 UTC
Documentation changes to explain log4j not capturing AccessLogValve events. Also, several clarifications and phrasing changes.
Comment 9 Mark Thomas 2013-08-29 08:29:05 UTC
Thanks. Patch applied and will be included in 8.0.0-RC2 onwards.
Comment 10 Konstantin Kolinko 2014-04-27 23:27:10 UTC
Documentation patches backported to Tomcat 7 in r1590521 and r1590522 , will be in 7.0.54.