[logback-dev] [GIT] Logback: the generic, reliable, fast and flexible logging framework. branch, master, updated. v_0.9.25-35-gbb61e53
added by portage for gitosis-gentoo
git-noreply at pixie.qos.ch
Wed Nov 17 22:33:09 CET 2010
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "Logback: the generic, reliable, fast and flexible logging framework.".
The branch, master has been updated
via bb61e53367abe61a360118f4a43ca45390d06462 (commit)
from 6d4fb9ec8008f6af55a0bc141221b46633510b7c (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=bb61e53367abe61a360118f4a43ca45390d06462
http://github.com/ceki/logback/commit/bb61e53367abe61a360118f4a43ca45390d06462
commit bb61e53367abe61a360118f4a43ca45390d06462
Author: Ceki Gulcu <ceki at qos.ch>
Date: Wed Nov 17 22:31:36 2010 +0100
ongoing work on the documentation
diff --git a/logback-site/src/site/pages/access.html b/logback-site/src/site/pages/access.html
index 6ae4543..3a0055c 100644
--- a/logback-site/src/site/pages/access.html
+++ b/logback-site/src/site/pages/access.html
@@ -8,11 +8,11 @@
<link rel="stylesheet" type="text/css" href="css/common.css" />
<link rel="stylesheet" type="text/css" href="css/screen.css" media="screen" />
<link rel="stylesheet" type="text/css" href="css/_print.css" media="print" />
-
+ <link rel="stylesheet" type="text/css" href="css/prettify.css" media="screen" />
</head>
- <body>
+ <body onload="prettyPrint()">
<script type="text/javascript">prefix='';</script>
-
+ <script type="text/javascript" src="js/prettify.js"></script>
<script src="templates/header.js" type="text/javascript"></script>
<div id="left">
<script src="templates/left.js" type="text/javascript"></script>
@@ -44,23 +44,25 @@
<a name="tomcat"></a>
<h1>Logback-access under Tomcat</h1>
- <p>To use logback-access with Tomcat, after downloading the logback
- distribution, place the files <em>logback-core-${project.version}.jar</em>
- and <em>logback-access-${project.version}.jar</em> under
- $TOMCAT_HOME/<b>server/lib/</b> directory, where $TOMCAT_HOME is
- the folder where you have installed Tomcat. We have tested
- logback-access with Tomcat versions 5.5.26 and 6.0.20.
+ <p>To use logback-access with Tomcat, after downloading the
+ logback distribution, place the files
+ <em>logback-core-${project.version}.jar</em> and
+ <em>logback-access-${project.version}.jar</em> under
+ $TOMCAT_HOME/lib/ directory, where $TOMCAT_HOME is the folder
+ where you have installed Tomcat. We have tested logback-access
+ with Tomcat version 6.0.20.
</p>
- <p>Place the logback-core and logback-access jars in
+ <!--
+ <p>If you placed logback-core and logback-access jars in
$TOMCAT_HOME/lib <em>and</em> your webapps do not use
logback-classic, then everything should be fine. If however your
webapps do indeed use logback-classic, in addition to
- <em>logback-classic.jar</em>,w make sure to bundle
+ <em>logback-classic.jar</em>, make sure to bundle
<code>logback-core.jar</code> under your webapps' WEB-INF/lib
directory as well.
</p>
-
+ -->
<h2>LogbackValve</h2>
@@ -77,7 +79,7 @@
add the following lines to the tomcat server configuration file,
namely <em>$TOMCAT_HOME/conf/server.xml</em>:
</p>
- <div class="source"><pre><Valve className="ch.qos.logback.access.tomcat.LogbackValve"/></pre></div>
+ <pre class="source"><Valve className="ch.qos.logback.access.tomcat.LogbackValve"/></pre>
<p>This line is usually nested within an <code><Engine></code>
or <code><Host></code> element.
@@ -112,8 +114,8 @@
the logback-access configuration file. Here is an example.
</p>
- <p class="source"><Valve className="ch.qos.logback.access.tomcat.LogbackValve"
- quiet="true" filename="c:/my-logback-access.xml"/></p>
+ <pre class="prettyprint source"><Valve className="ch.qos.logback.access.tomcat.LogbackValve"
+ quiet="true" filename="c:/my-logback-access.xml"/></pre>
<h3><a name="viewingStatusMessages"
href="#viewingStatusMessages">Viewing status messages</a></h3>
@@ -132,7 +134,7 @@
<p>To add this servlet to your web-application, add the following
lines to its <em>WEB-INF/web.xml</em> file.</p>
- <p class="source"> <servlet>
+ <pre class="prettyprint source"> <servlet>
<servlet-name>AccessViewStatusMessages</servlet-name>
<servlet-class>ch.qos.logback.access.ViewStatusMessagesServlet</servlet-class>
</servlet>
@@ -140,7 +142,7 @@
<servlet-mapping>
<servlet-name>AccessViewStatusMessages</servlet-name>
<url-pattern>/lbAccessStatus</url-pattern>
- </servlet-mapping></p>
+ </servlet-mapping></pre>
<p>The <code>ViewStatusMessages</code> servlet will available
under the URL <code>http://host/yourWebapp/lbAccessStatus</code>
@@ -180,13 +182,13 @@
jetty's main configuration file, namely
<em>$JETTY_HOME/etc/jetty.xml</em>:
</p>
- <div class="source"><pre><Ref id="requestLog">
+ <pre class="prettyprint source"><Ref id="requestLog">
<Set name="requestLog">
<New id="requestLogImpl"
class="ch.qos.logback.access.jetty.RequestLogImpl">
</New>
</Set>
-</Ref></pre></div>
+</Ref></pre>
<p>By default, <code>RequestLogImpl</code> looks for a logback
configuration file called <em>logback-access.xml</em>, in the same
@@ -202,60 +204,61 @@
<em>logback-access.xml</em> configuration file.
</p>
- <div class="source"><pre><Ref id="requestLog">
+ <pre class="prettyprint source"><Ref id="requestLog">
<Set name="requestLog">
<New id="requestLogImpl"
class="ch.qos.logback.access.jetty.RequestLogImpl">
</New>
<Set name="fileName">path/to/myaccess.xml</Set>
</Set>
-</Ref></pre></div>
+</Ref></pre>
<a name="configuration"></a>
<h1>Logback-access configuration</h1>
- <p>Although similar, the <em>logback-access.xml</em> file is slightly
- different than its more common counterpart in logback-classic.
- Appenders and Layouts are declared the exact same way. However, in
- the access module there is no notion of loggers and consequently
- logger elements are disallowed in logback-access configuration
- files.
+ <p>Although similar, the format of <em>logback-access.xml</em>
+ configuration file is slightly different than the configuration file
+ format logback-classic. Appenders and Layouts are declared the
+ exact same way. However, in the access module there is no notion of
+ loggers and consequently logger elements are disallowed.
</p>
+
<h3>Example 1: basic logback-access configuration</h3>
<p>
Here is a small but fully functional <em>logback-access.xml</em>
configuration file:
</p>
-<div class="source"><pre><configuration>
- <appender name="STDOUT"
- class="ch.qos.logback.core.ConsoleAppender">
- <layout
- class="ch.qos.logback.access.PatternLayout">
- <Pattern>%h %l %u %user %date "%r" %s %b</Pattern>
- </layout>
+ <pre class="prettyprint source"><configuration>
+ <!-- always a good activate OnConsoleStatusListener -->
+ <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" />
+
+ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+ <encoder>
+ <pattern>%h %l %u %user %date "%r" %s %b</pattern>
+ </encoder>
</appender>
<appender-ref ref="STDOUT" />
-</configuration></pre></div>
+</configuration></pre>
<p>
It declares a <code>ConsoleAppender</code> which prints its output
- on the console. The <code>ConsoleAppender</code> contains a
- <code>PatternLayout</code> object responsible to format this
- output. The log format is specified by the "%h %l %u %user %date
- "%r" %s %b" pattern which incidentally corresponds to Common Log
- Format (CLF). This format is recognized by log analyzers such as
- <a href="http://www.analog.cx/">Analog</a> or <a
- href="http://awstats.sourceforge.net/">AWStats</a>.
+ on the console. The <code>ConsoleAppender</code> contains an
+ <code>Encoder</code> object responsible for formatting output. The
+ log format is specified by the "%h %l %u %user %date "%r" %s %b"
+ pattern which incidentally corresponds to the Common Log Format
+ (CLF). This format is recognized by log analyzers such as <a
+ href="http://www.analog.cx/">Analog</a> or <a
+ href="http://awstats.sourceforge.net/">AWStats</a>.
</p>
<p>The words "common" or "clf" are interpreted as shorthands for
the said pattern. Thus, the following are all equivalent:
</p>
- <div class="source"><pre><Pattern>%h %l %u %user %date "%r" %s %b</Pattern>
-<Pattern>common</Pattern>
-<Pattern>clf</Pattern></pre></div>
+ <pre class="prettyprint source"><pattern>%h %l %u %user %date "%r" %s %b</pattern>
+<pattern>common</pattern>
+<pattern>clf</pattern></pre>
<p>The so called "combined" format is also widely recognized. It is
defined as the '%h %l %u %t "%r" %s %b "%i{Referer}"
@@ -263,15 +266,15 @@
"combined" as a shorthand. Thus, the following directive
</p>
- <div class="source"><pre><layout class="ch.qos.logback.access.PatternLayout">
- <Pattern>%h %l %u %t "%r" %s %b "%i{Referer}" "%i{User-Agent}"</Pattern>
-</layout></pre></div>
+ <pre class="prettyprint source"><encoder>
+ <pattern>%h %l %u %t "%r" %s %b "%i{Referer}" "%i{User-Agent}"</pattern>
+</encoder></pre>
<p>is equivalent to:</p>
- <div class="source"><pre><layout class="ch.qos.logback.access.PatternLayout">
- <Pattern>combined</Pattern>
-</layout></pre></div>
+ <pre class="prettyprint source"><encoder>
+ <pattern>combined</pattern>
+</encoder></pre>
<h3>Example 2: RollingFileAppender</h3>
@@ -279,26 +282,27 @@
<p>The configuration file below configures a daily rolling
<code>RollingFileAppender</code>. Note that due to the
<em>.zip</em> suffix included in the value for <span
- class="option">FileNamePattern</span> option, the log file are not
+ class="option">fileNamePattern</span> option, the log file are not
only rolled daily, but they are also automatically compressed.</p>
-<div class="source"><pre><configuration>
- <appender name="FILE"
- class="ch.qos.logback.core.rolling.RollingFileAppender">
- <File>access.log"</File>
- <rollingPolicy
- class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
- <FileNamePattern>access.%d{yyyy-MM-dd}.log.zip</FileNamePattern>
+ <pre class="prettyprint source"><configuration>
+ <!-- always a good activate OnConsoleStatusListener -->
+ <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" />
+
+ <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+ <file>access.log</file>
+ <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+ <fileNamePattern>access.%d{yyyy-MM-dd}.log.zip</fileNamePattern>
</rollingPolicy>
- <layout class="ch.qos.logback.access.PatternLayout">
- <Pattern>combined</Pattern>
- </layout>
+ <encoder>
+ <pattern>combined</pattern>
+ </encoder>
</appender>
<appender-ref ref="FILE" />
-</configuration></pre></div>
+</configuration></pre>
<p>These two examples should give you an idea of the possibilities
offered by logback-access. In principle, most if not all of the
@@ -344,7 +348,7 @@ CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"
Tomcat via the JConsole application, which can be started with the
following command:
</p>
-<div class="source"><pre>jconsole</pre></div>
+ <pre class="source">jconsole</pre>
<p>If you prefer MX4J to access your components via a web-based
interface, here is a short summary of the steps to follow. After
@@ -363,24 +367,21 @@ CATALINA_OPTS="$CATALINA_OPTS -Djavax.management.builder.initial=mx4j.server.MX4
<!-- in the "Add on extra jar files to CLASSPATH" section -->
CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div>
- <p>
- Finally, declare a new <code>Connector</code> in the
- <em>$TOMCAT_HOME/conf/server.xml</em> file:
- </p>
+ <p>Finally, declare a new <code>Connector</code> in the
+ <em>$TOMCAT_HOME/conf/server.xml</em> file: </p>
-<div class="source"><pre><Connector port="8050"
+ <pre class="prettyprint source"><Connector port="8050"
handler.list="mx"
mx.enabled="true"
mx.httpHost="localhost"
mx.httpPort="8082"
- protocol="AJP/1.3" /></pre></div>
+ protocol="AJP/1.3" /></pre>
- <p>
- Once Tomcat is started, you should be able to reach your JMX
+ <p> Once Tomcat is started, you should be able to reach your JMX
components by pointing your browser at the following URL:
</p>
-<div class="source"><pre>http://localhost:8082/</pre></div>
+ <pre class="source">http://localhost:8082/</pre>
<h3>Configuring Jetty</h3>
@@ -390,7 +391,7 @@ CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div>
added:
</p>
-<div class="source"><pre><Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/>
+ <pre class="prettyprint source"><Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/>
<!-- initialize the Jetty MBean container -->
<Get id="Container" name="container">
<Call name="addEventListener">
@@ -402,12 +403,12 @@ CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div>
</New>
</Arg>
</Call>
-</Get></pre></div>
+</Get></pre>
<p>Once Jetty is started with this configuration, all available
components can be reviewed at:
</p>
-<div class="source"><pre>http://localhost:8082/</pre></div>
+ <pre class="prettyprint source">http://localhost:8082/</pre>
<p>Logback-access' <code>RequestLogImpl</code> should be
available, including its <code>start()</code> and
@@ -427,43 +428,42 @@ CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div>
declare it, as any other filter:
</p>
-<div class="source"><pre><configuration>
+ <pre class="prettyprint source"><configuration>
<b><filter class="ch.qos.logback.access.filter.CountingFilter">
<name>countingFilter</name>
</filter></b>
- <appender name="STDOUT"
- class="ch.qos.logback.core.ConsoleAppender">
- <layout class="ch.qos.logback.access.PatternLayout">
- <Pattern>%h %l %u %t \"%r\" %s %b</Pattern>
- </layout>
+ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+ <encoder>
+ <pattern>%h %l %u %t \"%r\" %s %b</pattern>
+ </encoder>
</appender>
<appender-ref ref="STDOUT" />
-</configuration></pre></div>
+</configuration></pre>
- <p>
- This component registers itself to the JMX server and publishes
- the statistical data such as averages by minute, by hour, by
- day, by week, and by month. Last month's, week's, day's, hour's
- and minute's counts as well as the total number of access are
- also exposed.
+ <p>This component registers itself to the JMX server and publishes
+ the statistical data such as averages by minute, by hour, by day,
+ by week, and by month. Last month's, week's, day's, hour's and
+ minute's counts as well as the total number of access are also
+ exposed.
</p>
- <h2><code>TeeFilter</code></h2>
+ <h2><a name="teeFilter" href="#teeFilter"><code>TeeFilter</code></a></h2>
- <p>For debugging purposes, it is often handy to capture the client
- request as well as the server response as is. The
- <code>TeeFilter</code> was designed precisely for this purpose.
- </p>
+ <p>In order to diagnose bugs in a web-application, it is often
+ handy to capture the client's request as well as the server's
+ response as is. The <code>TeeFilter</code> was designed precisely
+ for this purpose.
+ </p>
- <p>The <code>TeeFilter</code> is a regular servlet filter. Like other
- servlet filters, it needs to be declared in your web-application's
- <em>web.xml</em> file:
-</p>
+ <p>The <code>TeeFilter</code> is a regular servlet filter. Like other
+ servlet filters, it needs to be declared in your web-application's
+ <em>web.xml</em> file:
+ </p>
-<div class="source"><filter>
+ <pre class="prettyprint source"><filter>
<filter-name>TeeFilter</filter-name>
<filter-class>ch.qos.logback.access.servlet.TeeFilter</filter-class>
</filter>
@@ -471,18 +471,16 @@ CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div>
<filter-mapping>
<filter-name>TeeFilter</filter-name>
<url-pattern>/*</url-pattern>
-</filter-mapping>
-</div>
+</filter-mapping></pre>
<p>We have tested <code>TeeFilter</code> to the best of our
ability. However, since it duplicates the input stream of the
request and the output stream of the response, it may interfere with
- your application. For large input or output, it will add measurable
- latency. Although we have already fixed all currently known bugs,
- <code>TeeFilter</code> has broken otherwise correctly behaving
- applications. Thus, in case of doubt, do not hesitate to disable
- <code>TeeFilter</code>.
-
+ your application. Moreover, for large input or output sizes, it will
+ add measurable latency. Although we have already fixed all currently
+ known bugs, <code>TeeFilter</code> has broken otherwise correctly
+ behaving applications in the past. Thus, in case of doubt, do not
+ hesitate to disable <code>TeeFilter</code>.
</p>
<p>Once <code>TeeFilter</code> is installed, the <a
@@ -496,7 +494,7 @@ CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div>
output the full contents of the request and response on the console.
</p>
- <p class="source"><configuration>
+ <pre class="prettyprint source"><configuration>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<layout class="ch.qos.logback.access.PatternLayout">
<Pattern>%fullRequest%n%n%fullResponse</Pattern>
@@ -504,15 +502,16 @@ CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div>
</appender>
<appender-ref ref="STDOUT" />
-</configuration></p>
+</configuration></pre>
- <p>Few clicks accessing the <a href="demo.html">logback-demo</a>
- application configured as outlined above, yields:</p>
+ <p>Here is the output generated when accessing the <a
+ href="demo.html">logback-demo</a> application configured as shown
+ above, yields:</p>
<p class="source"><b>GET /logback-demo/index.jsp HTTP/1.1</b>
Host: localhost:8080
-User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.0.11) Gecko/20070312 Firefox/1.5.0.11
-Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
+User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8) Gecko/20070312 Firefox/1.5.0
+Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
@@ -542,6 +541,43 @@ Set-Cookie: JSESSIONID=bgebt99ce9om;path=/logback-demo
<p> </p>
+ <p>As mentioned previously, while extremely useful during problem
+ hunting, <code>TeeFilter</code> can introduce new problems.
+ Consequently, we do not recommend having <code>TeeFilter</code>
+ active in production systems. In order to avoid shipping different
+ code for test and production environments, <code>TeeFilter</code>
+ supports <code>includes</code> and <code>excludes</code> parameters.
+ <code>TeeFilter</code> will be active if the current host is listed
+ in the includes list and absent in the excludes list. An empty
+ includes list is interepreted as to contain all possible host names
+ in the universe.
+ </p>
+
+ <p>To enable <code>TeeFilter</code> only on the hosts named "orion"
+ and "gemini" and disabled elsewhere you would write:</p>
+
+ <pre class="prettyprint source"><filter>
+ <filter-name>TeeFilter</filter-name>
+ <filter-class>ch.qos.logback.access.servlet.TeeFilter</filter-class>
+ <init-param>
+ <param-name>includes</param-name>
+ <param-value>orion, gemini</param-value>
+ </init-param>
+</filter> </pre>
+
+ <p>To enable <code>TeeFilter</code> on all hosts <em>except</em>
+ hosts named "orion" and "gemini" you would write:</p>
+
+ <pre class="prettyprint source"><filter>
+ <filter-name>TeeFilter</filter-name>
+ <filter-class>ch.qos.logback.access.servlet.TeeFilter</filter-class>
+ <init-param>
+ <param-name>excludes</param-name>
+ <param-value>orion, gemini</param-value>
+ </init-param>
+</filter> </pre>
+
+
<script src="templates/footer.js" type="text/javascript"></script>
</div>
diff --git a/logback-site/src/site/pages/reasonsToSwitch.html b/logback-site/src/site/pages/reasonsToSwitch.html
index cdb0b78..ed2bcd3 100644
--- a/logback-site/src/site/pages/reasonsToSwitch.html
+++ b/logback-site/src/site/pages/reasonsToSwitch.html
@@ -251,6 +251,18 @@ java.lang.Exception: 99 is invalid
files older than 12 months will be automatically removed.
</p>
+
+ <h3><a name="logbackAccess" href="#logbackAccess">Logback-access,
+ i.e. HTTP-access logging with brains, is an integral part of
+ logback</a></h3>
+
+ <p>Last but not least, the logback-access module, part of the
+ logback distribution, integrates with Servlet containers such as
+ Jetty or Tomcat to provide rich and powerful HTTP-access log
+ functionality. Since logback-access was part of the initial
+ design, all the logback-classic features you came love are
+ available in logback-access as well.</p>
+
<h3><a name="inSummary" href="#inSummary">In summary</a></h3>
<p>We have listed a number of reasons for preferring logback over
-----------------------------------------------------------------------
Summary of changes:
logback-site/src/site/pages/access.html | 262 ++++++++++++----------
logback-site/src/site/pages/reasonsToSwitch.html | 12 +
2 files changed, 161 insertions(+), 113 deletions(-)
hooks/post-receive
--
Logback: the generic, reliable, fast and flexible logging framework.
More information about the logback-dev
mailing list