Author: seb Date: Fri Oct 6 09:38:58 2006 New Revision: 626 Added: logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml Modified: logback/trunk/logback-access/src/main/java/ch/qos/logback/access/PatternLayout.java logback/trunk/logback-access/src/main/java/ch/qos/logback/access/jetty/RequestLogImpl.java logback/trunk/logback-access/src/main/java/ch/qos/logback/access/net/SMTPAppender.java logback/trunk/logback-access/src/main/java/ch/qos/logback/access/pattern/PostContentConverter.java logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Log: - added documentation for logback access. - removed PostContentConverter from PatternLayout. Modified: logback/trunk/logback-access/src/main/java/ch/qos/logback/access/PatternLayout.java ============================================================================== --- logback/trunk/logback-access/src/main/java/ch/qos/logback/access/PatternLayout.java (original) +++ logback/trunk/logback-access/src/main/java/ch/qos/logback/access/PatternLayout.java Fri Oct 6 09:38:58 2006 @@ -36,39 +36,216 @@ import ch.qos.logback.core.pattern.Converter; import ch.qos.logback.core.pattern.PatternLayoutBase; - +/** + * <p> + * This class is a module-specific implementation of + * {@link ch.qos.logback.classic.PatternLayout} to allow http-specific patterns + * to be used. The <code>ch.qos.logback.access.PatternLayout</code> provides a + * way to format the logging output that is just as easy and flexible as the + * usual <code>PatternLayout</code>. + * </p> + * <p> + * For more information about the general use of a <code>PatternLayout</code>, + * please refer to logback classic's + * <code>ch.qos.logback.classic.PatternLayout</code>. + * </p> + * <p> + * Logback access' <code>PatternLayout</code> offers the following + * possibilities: + * </p> + * <table border="1" CELLPADDING="8"> + * <th>Conversion Character or Word</th> + * <th>Effect</th> + * + * <tr> + * <td align="center"><b>a / remoteIP</b></td> + * <td> + * <p> + * Remote IP address. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>A / localIP</b></td> + * <td> + * <p> + * Local IP address. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>b / B / byteSent</b></td> + * <td> + * <p> + * Response's content length. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>h / clientHost</b></td> + * <td> + * <p> + * Remote host. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>H / protocol</b></td> + * <td> + * <p> + * Request protocol. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>i / header</b></td> + * <td> + * <p> + * Request header. This conversion word can be followed by a key whose + * corresponding data will be extracted from the header information. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>m / requestMethod</b></td> + * <td> + * <p> + * Request method. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>r / requestURL</b></td> + * <td> + * <p> + * URL requested. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>s / statusCode</b></td> + * <td> + * <p> + * Status code of the request. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>t / date</b></td> + * <td> + * <p> + * Date of the event. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>u / user</b></td> + * <td> + * <p> + * Remote user. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>U / requestURI</b></td> + * <td> + * <p> + * Requested URI. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>v / server</b></td> + * <td> + * <p> + * Server name. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>localPort</b></td> + * <td> + * <p> + * Local port. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>reqAttribute</b></td> + * <td> + * <p> + * Attribute of the request. Just like the request header conversion word, + * reqAttribute can be followed by a key. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>reqCookie</b></td> + * <td> + * <p> + * Request cookie. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>responseHeader</b></td> + * <td> + * <p> + * Header of the response. Just like the request header conversion word, + * responseHeader can be followed by a key. + * </p> + * </td> + * </tr> + * <tr> + * <td align="center"><b>reqParameter</b></td> + * <td> + * <p> + * Parameter of the response. Just like the request header conversion word, + * reqParameter can be followed by a key. + * </p> + * </td> + * </tr> + * </table> + * + * @author Ceki Gülcü + * @author Sébastien Pennec + */ public class PatternLayout extends PatternLayoutBase implements AccessLayout { static final Map<String, String> defaultConverterMap = new HashMap<String, String>(); public static String CLF_PATTERN = "%h %l %u %t \"%r\" %s %b"; - + static { defaultConverterMap.put("a", RemoteIPAddressConverter.class.getName()); - defaultConverterMap.put("remoteIP", RemoteIPAddressConverter.class.getName()); + defaultConverterMap.put("remoteIP", RemoteIPAddressConverter.class + .getName()); defaultConverterMap.put("A", LocalIPAddressConverter.class.getName()); defaultConverterMap.put("localIP", LocalIPAddressConverter.class.getName()); defaultConverterMap.put("b", ContentLengthConverter.class.getName()); defaultConverterMap.put("B", ContentLengthConverter.class.getName()); - defaultConverterMap.put("bytesSent", ContentLengthConverter.class.getName()); + defaultConverterMap + .put("bytesSent", ContentLengthConverter.class.getName()); defaultConverterMap.put("h", RemoteHostConverter.class.getName()); defaultConverterMap.put("clientHost", RemoteHostConverter.class.getName()); defaultConverterMap.put("H", RequestProtocolConverter.class.getName()); - defaultConverterMap.put("protocol", RequestProtocolConverter.class.getName()); - + defaultConverterMap.put("protocol", RequestProtocolConverter.class + .getName()); + defaultConverterMap.put("i", RequestHeaderConverter.class.getName()); defaultConverterMap.put("header", RequestHeaderConverter.class.getName()); - + defaultConverterMap.put("l", NAConverter.class.getName()); - + defaultConverterMap.put("m", RequestMethodConverter.class.getName()); - defaultConverterMap.put("requestMethod", RequestMethodConverter.class.getName()); - + defaultConverterMap.put("requestMethod", RequestMethodConverter.class + .getName()); + defaultConverterMap.put("r", RequestURLConverter.class.getName()); defaultConverterMap.put("requestURL", RequestURLConverter.class.getName()); @@ -80,23 +257,26 @@ defaultConverterMap.put("u", RemoteUserConverter.class.getName()); defaultConverterMap.put("user", RemoteUserConverter.class.getName()); - + defaultConverterMap.put("U", RequestURIConverter.class.getName()); defaultConverterMap.put("requestURI", RequestURIConverter.class.getName()); - + defaultConverterMap.put("v", ServerNameConverter.class.getName()); defaultConverterMap.put("server", ServerNameConverter.class.getName()); - + defaultConverterMap.put("localPort", LocalPortConverter.class.getName()); - defaultConverterMap.put("reqAttribute", RequestAttributeConverter.class.getName()); - defaultConverterMap.put("reqCookie", RequestCookieConverter.class.getName()); - defaultConverterMap.put("responseHeader", ResponseHeaderConverter.class.getName()); - defaultConverterMap.put("reqParameter", RequestParameterConverter.class.getName()); - - + defaultConverterMap.put("reqAttribute", RequestAttributeConverter.class + .getName()); + defaultConverterMap + .put("reqCookie", RequestCookieConverter.class.getName()); + defaultConverterMap.put("responseHeader", ResponseHeaderConverter.class + .getName()); + defaultConverterMap.put("reqParameter", RequestParameterConverter.class + .getName()); + defaultConverterMap.put("n", LineSeparatorConverter.class.getName()); } - + public PatternLayout() { // set a default value for pattern setPattern(CLF_PATTERN); @@ -115,7 +295,7 @@ protected void postCompileProcessing(Converter head) { Converter tail = findTail(head); Converter newLineConverter = new LineSeparatorConverter(); - if(tail == null) { + if (tail == null) { head = newLineConverter; } else { if (!(tail instanceof LineSeparatorConverter)) { @@ -135,6 +315,5 @@ public String doLayout(Object o) { return doLayout((AccessEvent) o); } - } Modified: logback/trunk/logback-access/src/main/java/ch/qos/logback/access/jetty/RequestLogImpl.java ============================================================================== --- logback/trunk/logback-access/src/main/java/ch/qos/logback/access/jetty/RequestLogImpl.java (original) +++ logback/trunk/logback-access/src/main/java/ch/qos/logback/access/jetty/RequestLogImpl.java Fri Oct 6 09:38:58 2006 @@ -24,56 +24,80 @@ * LoggerContext does. It also provides containers for properties. * <p> * To configure jetty in order to use RequestLogImpl, the following lines must - * be added to the jetty configuration file: + * be added to the jetty configuration file, namely <em>etc/jetty.xml</em>: + * * <pre> - * <Ref id="requestLog"> - * <Set name="requestLog"> - * <New id="requestLogImpl" class="ch.qos.logback.access.jetty.RequestLogImpl"></New> - * </Set> - * </Ref> + * <Ref id="requestLog"> + * <Set name="requestLog"> + * <New id="requestLogImpl" class="ch.qos.logback.access.jetty.RequestLogImpl"></New> + * </Set> + * </Ref> * </pre> + * * By default, RequestLogImpl looks for a logback configuration file called * logback.xml, in the same folder where jetty.xml is located, that is - * /etc/logback.xml. The logback.xml file is slightly different than the usual + * <em>etc/logback.xml</em>. The logback.xml file is slightly different than the usual * logback classic configuration file. Most of it is the same: Appenders and * Layouts are declared the exact same way. However, loggers elements are not * allowed. * <p> - * It is possible to put the logback configuration file anywhere, as long as it's path is - * specified. Here is another example, with a path to the logback.xml file. + * It is possible to put the logback configuration file anywhere, as long as + * it's path is specified. Here is another example, with a path to the + * logback.xml file. + * * <pre> - * <Ref id="requestLog"> - * <Set name="requestLog"> - * <New id="requestLogImpl" class="ch.qos.logback.access.jetty.RequestLogImpl"></New> - * <Set name="fileName">path/to/logback.xml</Set> - * </Set> - * </Ref> + * <Ref id="requestLog"> + * <Set name="requestLog"> + * <New id="requestLogImpl" class="ch.qos.logback.access.jetty.RequestLogImpl"></New> + * <Set name="fileName">path/to/logback.xml</Set> + * </Set> + * </Ref> * </pre> + * * <p> * Here is a sample logback.xml file that can be used right away: + * * <pre> - * <configuration> - * <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> - * <layout class="ch.qos.logback.access.PatternLayout"> - * <param name="Pattern" value="%date %server %remoteIP %clientHost %user %requestURL" /> - * </layout> - * </appender> - * - * <appender-ref ref="STDOUT" /> - * </configuration> + * <configuration> + * <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + * <layout class="ch.qos.logback.access.PatternLayout"> + * <param name="Pattern" value="%date %server %remoteIP %clientHost %user %requestURL" /> + * </layout> + * </appender> + * + * <appender-ref ref="STDOUT" /> + * </configuration> * </pre> * + * <p> + * Another configuration file, using SMTPAppender, could be: * + * <pre> + * <configuration> + * <appender name="SMTP" class="ch.qos.logback.access.net.SMTPAppender"> + * <layout class="ch.qos.logback.access.PatternLayout"> + * <param name="pattern" value="%remoteIP [%date] %requestURL %statusCode %bytesSent" /> + * </layout> + * <param name="From" value="sender@domaine.org" /> + * <param name="SMTPHost" value="mail.domain.org" /> + * <param name="Subject" value="Last Event: %statusCode %requestURL" /> + * <param name="To" value="server_admin@domain.org" /> + * </appender> + * <appender-ref ref="SMTP" /> + * </configuration> + * </pre> * <p> - * A special, module-specific implementation of PatternLayout was implemented to allow - * http-specific patterns to be used. The {@link ch.qos.logback.access.PatternLayout} provides - * a way to format the logging output that is just as easy and flexible as the usual - * PatternLayout. - * For more information about the general use of a PatternLayout, please refer to logback - * classic's {@link ch.qos.logback.classic.PatternLayout}. For information about logback - * access' specific PatternLayout, please refer to it's javadoc. + * A special, module-specific implementation of PatternLayout was implemented to + * allow http-specific patterns to be used. The + * {@link ch.qos.logback.access.PatternLayout} provides a way to format the + * logging output that is just as easy and flexible as the usual PatternLayout. + * For more information about the general use of a PatternLayout, please refer + * to logback classic's {@link ch.qos.logback.classic.PatternLayout}. For + * information about logback access' specific PatternLayout, please refer to + * it's javadoc. * * @author Ceki Gülcü + * @author Sébastien Pennec */ public class RequestLogImpl extends ContextBase implements RequestLog, AppenderAttachable { Modified: logback/trunk/logback-access/src/main/java/ch/qos/logback/access/net/SMTPAppender.java ============================================================================== --- logback/trunk/logback-access/src/main/java/ch/qos/logback/access/net/SMTPAppender.java (original) +++ logback/trunk/logback-access/src/main/java/ch/qos/logback/access/net/SMTPAppender.java Fri Oct 6 09:38:58 2006 @@ -20,8 +20,7 @@ import ch.qos.logback.core.rolling.TriggeringPolicy; /** - * Send an e-mail when a specific access event occurs, typically on errors or - * fatal errors. + * Send an e-mail when a specific access event occurs, typically on server errors. * * <p> * The number of access events delivered in this e-mail depend on the value of Modified: logback/trunk/logback-access/src/main/java/ch/qos/logback/access/pattern/PostContentConverter.java ============================================================================== --- logback/trunk/logback-access/src/main/java/ch/qos/logback/access/pattern/PostContentConverter.java (original) +++ logback/trunk/logback-access/src/main/java/ch/qos/logback/access/pattern/PostContentConverter.java Fri Oct 6 09:38:58 2006 @@ -2,6 +2,15 @@ import ch.qos.logback.access.spi.AccessEvent; +/** + * This class is tied to the <code>postContent</code> conversion pattern. + * + * It has been removed from the {@link ch.qos.logback.access.PatternLayout} since + * it needs further testing before being used widely. + * + * @author Ceki Gülcü + * @author Sébastien Pennec + */ public class PostContentConverter extends AccessConverter { @Override Added: logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml Fri Oct 6 09:38:58 2006 @@ -0,0 +1,322 @@ +<document> + <!-- + + Warning: do not use any auto-format function on this file. + Since "source" divs use pre as white-space, it affects the + look of the code parts in this document. + + --> + + + <body> + <h2>Access log with logback and Jetty</h2> + <div class="author"> + Authors: Ceki Gülcü, Sébastien Pennec + </div> + + + <table> + <tr> + <td valign="top" align="top"> + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-nd/2.5/"> + <img alt="Creative Commons License" border="0" + valign="top" align="top" + src="http://creativecommons.org/images/public/somerights20.png" /> + </a> + </td> + <td> + <p>Copyright © 2000-2006, QOS.ch</p> + + <p> + This work is licensed under a + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-nd/2.5/"> + Creative Commons + Attribution-Noncommercial-No Derivative + Works 2.5 License + </a> + . + </p> + </td> + </tr> + </table> + + <h2>Introduction</h2> + + <p> + Since its first design drafts, logback has been concieved as a modular framework. + Being able to use logback's internal core in many situations, without heavy coding or + complex specific configuration was one of our goals. + </p> + <p> + Lobgack access integrates with Servlet containers such as Jetty and Tomcat to provide + HTTP-access log functionality. + </p> + <p> + Integrating logback into Jetty is very simple. Once done, one can benefit of many of + logback's flexibility and reliability. + </p> + + <h2>Logback's RequestLog implementation</h2> + + <p> + Logback's <code>ch.qos.logback.access.jetty.RequestLogImpl</code> is an + implementation of jetty's <code>RequestLog</code> interface. + </p> + <p> + It can be seen as logback classic's <code>LoggerContext</code>. + </p> + <p> + In logback, logging destinations are called Appenders. These classes + can be attached directly to <code>RequestLogImpl</code>. + </p> + <p>Logback's internal error reporting system is based on Status objects. + <code>RequestLogImpl</code> uses the same <code>StatusManager</code> + as <code>LoggerContext</code> does. It also provides containers for properties. + </p> + <p> + To configure jetty in order to use <code>RequestLogImpl</code>, the + following lines must be added to the jetty configuration + file, namely <em>etc/jetty.xml</em>: + </p> + <pre> +<Ref id="requestLog"> + <Set name="requestLog"> + <New id="requestLogImpl" + class="ch.qos.logback.access.jetty.RequestLogImpl"> + </New> + </Set> +</Ref> + </pre> + <p> + By default, <code>RequestLogImpl</code> looks for a logback configuration + file called logback.xml, in the same folder where jetty.xml + is located, that is <em>etc/logback.xml</em>. The logback.xml file + is slightly different than the usual logback classic + configuration file. Most of it is the same: Appenders and + Layouts (which are logback components to format logging output) + are declared the exact same way. However, loggers + elements are not allowed. It is possible to put the logback + configuration file anywhere, as long as it's path is + specified. Here is another example, with a path to the + logback.xml file. + </p> + <pre> +<Ref id="requestLog"> + <Set name="requestLog"> + <New id="requestLogImpl" + class="ch.qos.logback.access.jetty.RequestLogImpl"> + </New> + <Set name="fileName">path/to/logback.xml</Set> + </Set> +</Ref> + </pre> + <p> + Here is a sample logback.xml file that can be used right + away: + </p> + <pre> +<configuration> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout + class="ch.qos.logback.access.PatternLayout"> + <param name="Pattern" + value="%date %server %remoteIP %clientHost %user %requestURL" /> + </layout> + </appender> + + <appender-ref ref="STDOUT" /> +</configuration> + </pre> + <p>Another configuration file, using logback access <code>SMTPAppender</code>, could be:</p> + <pre> +<configuration> + <appender name="SMTP" + class="ch.qos.logback.access.net.SMTPAppender"> + <layout + class="ch.qos.logback.access.PatternLayout"> + <param name="pattern" + value="%remoteIP [%date] %requestURL %statusCode %bytesSent" /> + </layout> + <param name="From" value="sender@domaine.org" /> + <param name="SMTPHost" value="mail.domain.org" /> + <param name="Subject" + value="Last Event: %statusCode %requestURL" /> + <param name="To" value="server_admin@domain.org" /> + </appender> + <appender-ref ref="SMTP" /> +</configuration> + </pre> + <p> + A special, module-specific implementation of <code>PatternLayout</code> + was implemented to allow http-specific patterns to be used. + The <code>ch.qos.logback.access.PatternLayout</code> provides a way to + format the logging output that is just as easy and flexible + as the usual <code>PatternLayout</code>. + </p> + <p> + For more information about the + general use of a <code>PatternLayout</code>, please refer to logback + classic's <code>ch.qos.logback.classic.PatternLayout</code>. + </p> + <p> + Logback access <code>PatternLayout</code> offers the following possibilities: + </p> + <table border="1" CELLPADDING="8"> + <th align="center">Conversion Character or Word</th> + <th align="center">Effect</th> + + <tr> + <td align="center"><b>a / remoteIP</b></td> + <td> + <p> + Remote IP address. + </p> + </td> + </tr> + <tr> + <td align="center"><b>A / localIP</b></td> + <td> + <p> + Local IP address. + </p> + </td> + </tr> + <tr> + <td align="center"><b>b / B / byteSent</b></td> + <td> + <p> + Response's content length. + </p> + </td> + </tr> + <tr> + <td align="center"><b>h / clientHost</b></td> + <td> + <p> + Remote host. + </p> + </td> + </tr> + <tr> + <td align="center"><b>H / protocol</b></td> + <td> + <p> + Request protocol. + </p> + </td> + </tr> + <tr> + <td align="center"><b>i / header</b></td> + <td> + <p> + Request header. This conversion word can be followed by a key + whose corresponding data will be extracted from the header information. + </p> + </td> + </tr> + <tr> + <td align="center"><b>m / requestMethod</b></td> + <td> + <p> + Request method. + </p> + </td> + </tr> + <tr> + <td align="center"><b>r / requestURL</b></td> + <td> + <p> + URL requested. + </p> + </td> + </tr> + <tr> + <td align="center"><b>s / statusCode</b></td> + <td> + <p> + Status code of the request. + </p> + </td> + </tr> + <tr> + <td align="center"><b>t / date</b></td> + <td> + <p> + Date of the event. + </p> + </td> + </tr> + <tr> + <td align="center"><b>u / user</b></td> + <td> + <p> + Remote user. + </p> + </td> + </tr> + <tr> + <td align="center"><b>U / requestURI</b></td> + <td> + <p> + Requested URI. + </p> + </td> + </tr> + <tr> + <td align="center"><b>v / server</b></td> + <td> + <p> + Server name. + </p> + </td> + </tr> + <tr> + <td align="center"><b>localPort</b></td> + <td> + <p> + Local port. + </p> + </td> + </tr> + <tr> + <td align="center"><b>reqAttribute</b></td> + <td> + <p> + Attribute of the request. Just like the request header + conversion word, reqAttribute can be followed by a key. + </p> + </td> + </tr> + <tr> + <td align="center"><b>reqCookie</b></td> + <td> + <p> + Request cookie. Just like the request header + conversion word, reqCookie can be followed by a key. + </p> + </td> + </tr> + <tr> + <td align="center"><b>responseHeader</b></td> + <td> + <p> + Header of the response. Just like the request header + conversion word, responseHeader can be followed by a key. + </p> + </td> + </tr> + <tr> + <td align="center"><b>reqParameter</b></td> + <td> + <p> + Parameter of the response. Just like the request header + conversion word, reqParameter can be followed by a key. + </p> + </td> + </tr> + </table> + </body> +</document> Modified: logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Fri Oct 6 09:38:58 2006 @@ -17,9 +17,11 @@ <li> <a href="shortIntro.html"><b>A short introduction to logback-classic</b></a> </li> - <li> - <a href="apidocs/index.html"><b>javadoc</b></a> + <a href="accessLogJetty.html"><b>A short introduction to access logging with logback-access and Jetty</b></a> + </li> + <li> + <a href="apidocs/index.html"><b>Javadoc</b></a> </li> </ul>