Author: seb Date: Mon Nov 6 20:21:29 2006 New Revision: 876 Added: logback/trunk/logback-examples/src/main/java/chapter4/mail/ logback/trunk/logback-examples/src/main/java/chapter4/mail/CounterBasedTP.java logback/trunk/logback-examples/src/main/java/chapter4/mail/EMail.java logback/trunk/logback-examples/src/main/java/chapter4/mail/mail1.xml logback/trunk/logback-examples/src/main/java/chapter4/mail/mail2.xml logback/trunk/logback-examples/src/main/java/chapter4/mail/mail3.xml Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/SimpleSocketServer.java logback/trunk/logback-examples/src/main/java/chapter4/socket/server1.xml logback/trunk/logback-examples/src/main/java/chapter4/socket/server2.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml Log: on going work, added SMTPAppender doc + fixes on other examples Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/SimpleSocketServer.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/SimpleSocketServer.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/SimpleSocketServer.java Mon Nov 6 20:21:29 2006 @@ -18,7 +18,6 @@ import ch.qos.logback.classic.LoggerContext; import ch.qos.logback.classic.joran.JoranConfigurator; import ch.qos.logback.core.joran.spi.JoranException; -import ch.qos.logback.core.util.StatusPrinter; /** * A simple {@link SocketNode} based server. @@ -96,7 +95,7 @@ lc.reset(); configurator.setContext(lc); configurator.doConfigure(configFile); - StatusPrinter.print(lc); + //StatusPrinter.print(lc); } } } Added: logback/trunk/logback-examples/src/main/java/chapter4/mail/CounterBasedTP.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter4/mail/CounterBasedTP.java Mon Nov 6 20:21:29 2006 @@ -0,0 +1,37 @@ +/** + * Logback: the reliable, generic, fast and flexible logging framework. + * + * Copyright (C) 1999-2006, QOS.ch + * + * This library is free software, you can redistribute it and/or modify it under + * the terms of the GNU Lesser General Public License as published by the Free + * Software Foundation. + */ + +package chapter4.mail; + +import java.io.File; +import ch.qos.logback.core.rolling.TriggeringPolicyBase; + + +/** + * A simple TriggeringPolicy implementation that triggers + * email transmission after 1024 events regardless of event level. + * */ +public class CounterBasedTP extends TriggeringPolicyBase { + boolean started; + static int LIMIT = 1024; + int counter = 0; + + public boolean isTriggeringEvent(File file, Object event) { + counter++; + + if (counter == LIMIT) { + counter = 0; + + return true; + } else { + return false; + } + } +} Added: logback/trunk/logback-examples/src/main/java/chapter4/mail/EMail.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter4/mail/EMail.java Mon Nov 6 20:21:29 2006 @@ -0,0 +1,66 @@ +/** + * Logback: the reliable, generic, fast and flexible logging framework. + * + * Copyright (C) 1999-2006, QOS.ch + * + * This library is free software, you can redistribute it and/or modify it under + * the terms of the GNU Lesser General Public License as published by the Free + * Software Foundation. + */ + +package chapter4.mail; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.LoggerContext; +import ch.qos.logback.classic.joran.JoranConfigurator; + + + +/** + * This application generates log messages in numbers specified by the + * user. It is intended to let users test RollingFileAppender. See + * also configuration scripts rolling.properties and rolling.xml. + * */ +public class EMail { + static public void main(String[] args) throws Exception { + if (args.length != 2) { + usage("Wrong number of arguments."); + } + + int runLength = Integer.parseInt(args[0]); + String configFile = args[1]; + + if (configFile.endsWith(".xml")) { + LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + JoranConfigurator configurator = new JoranConfigurator(); + lc.reset(); + configurator.setContext(lc); + configurator.doConfigure(configFile); + //StatusPrinter.print(lc); + } + + Logger logger = LoggerFactory.getLogger(EMail.class); + + for (int i = 1; i <= runLength; i++) { + if ((i % 10) < 9) { + logger.debug("This is a debug message. Message number: " + i); + } else { + logger.warn("This is a warning message. Message number: " + i); + } + } + + logger.error("At last an error.", new Exception("Just testing")); + } + + static void usage(String msg) { + System.err.println(msg); + System.err.println("Usage: java " + EMail.class.getName() + + " runLength configFile\n" + + " runLength (integer) the number of logs to generate\n" + + " configFile a logback configuration file in XML format." + + " XML files must have a '.xml' extension."); + System.exit(1); + } +} Added: logback/trunk/logback-examples/src/main/java/chapter4/mail/mail1.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter4/mail/mail1.xml Mon Nov 6 20:21:29 2006 @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<!-- ========================================================== --> +<!-- Sample SMTPAppender configuration using the PatternLayout --> +<!-- ========================================================== --> + +<configuration> + + <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> + <SMTPHost>ADDRESS-OF-YOUR-SMTP-HOST</SMTPHost> + <To>DESTINATION-EMAIL</To> + <From>SENDER-EMAIL</From> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%date %-5level %logger - %message%n</Pattern> + </layout> + </appender> + + <root> + <level value="debug"/> + <appender-ref ref="EMAIL" /> + </root> +</configuration> Added: logback/trunk/logback-examples/src/main/java/chapter4/mail/mail2.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter4/mail/mail2.xml Mon Nov 6 20:21:29 2006 @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<!-- ======================================================= --> +<!-- Sample SMTPAppender configuration using the HTMLLayout --> +<!-- ======================================================= --> + +<configuration> + + <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> + <SMTPHost>${smtpHost}</SMTPHost> + <To>${to}</To> + <From>${from}</From> + <layout class="ch.qos.logback.classic.html.HTMLLayout"/> + </appender> + + <root> + <level value="debug"/> + <appender-ref ref="EMAIL" /> + </root> +</configuration> + + Added: logback/trunk/logback-examples/src/main/java/chapter4/mail/mail3.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter4/mail/mail3.xml Mon Nov 6 20:21:29 2006 @@ -0,0 +1,24 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<!-- ============================================================= --> +<!-- Sample SMTPAppender configuration using the HTMLLayout and a --> +<!-- custom trigger event evaluator. --> +<!-- ============================================================= --> + +<configuration> + <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> + <EvaluatorClass>chapter4.mail.CounterBasedTP</EvaluatorClass> + <BufferSize>1050</BufferSize> + <SMTPHost>${smtpHost}</SMTPHost> + <To>${to}</To> + <From>${from}</From> + <layout class="ch.qos.logback.classic.html.HTMLLayout"/> + </appender> + + <root> + <level value ="debug"/> + <appender-ref ref="EMAIL" /> + </root> +</configuration> + + Modified: logback/trunk/logback-examples/src/main/java/chapter4/socket/server1.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter4/socket/server1.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter4/socket/server1.xml Mon Nov 6 20:21:29 2006 @@ -12,7 +12,7 @@ <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%d %-5p [%t] %c - %m%n</Pattern> + <Pattern>%date %-5level [%thread] %logger - %message%n</Pattern> </layout> </appender> @@ -32,7 +32,7 @@ </triggeringPolicy> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%r %-5p %c - %m%n</Pattern> + <Pattern>%relative %-5level %logger - %message%n</Pattern> </layout> </appender> Modified: logback/trunk/logback-examples/src/main/java/chapter4/socket/server2.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter4/socket/server2.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter4/socket/server2.xml Mon Nov 6 20:21:29 2006 @@ -11,7 +11,7 @@ <!-- Notice the %file and %line patterns in the Pattern. --> <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%date %-5level [%thread] [%file:%line] %logger - %msg%n</Pattern> + <Pattern>%date %-5level [%thread] [%file:%line] %logger - %message%n</Pattern> </layout> </appender> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml Mon Nov 6 20:21:29 2006 @@ -584,7 +584,7 @@ renames files according to a fixed window algorithm as described below. </p> <p> - The <b>File</b>property, which is configured in the + The <b>File</b> property, which is configured in the <code>FileAppender</code> element, is required. It represents the name of the file where current logging output will be written. The <b>FileNamePattern</b> option represents the file name pattern for the archived (rolled over) log files. @@ -1078,11 +1078,6 @@ <em>5MB</em>, <em>500KB</em> or <em>2GB</em> are all valid. </p> <p> - <b>Althought values expressed in <em>GB</em> are possible, - we do not recommand setting the <span class="option">MaxFileSize</span> - option to a value bigger than XXX GB</b>. - </p> - <p> Here is a sample configuration with a <code>RollingFileAppender</code> using a <code>SizeBasedTriggeringPolicy</code>. </p> @@ -1259,7 +1254,7 @@ start <code>SimpleSocketServer</code> with the following command: </p> -<div class="source"><pre> java ch.qos.logback.classic.net.SimpleSocketServer 6000 \ +<div class="source"><pre>java ch.qos.logback.classic.net.SimpleSocketServer 6000 \ chapter4/socket/server1.xml </pre></div> @@ -1305,7 +1300,7 @@ and attaches it to the root logger. </p> - <em>Example 4.1: SocketAppender configuration (<a href="../xref/chapter4/socket/client1.html">logback-examples/src/main/java/chapter4/socket/client1.xml</a>)</em> + <em>Example 4.2: SocketAppender configuration (logback-examples/src/main/java/chapter4/socket/client1.xml)</em> <div class="source"><pre><configuration> <appender name="SOCKET" class="ch.qos.logback.classic.net.SocketAppender"> @@ -1380,11 +1375,265 @@ As an exercise, you may wish to setup two servers where the first server tunnels the events it receives from its clients to a second server. </p> + + <a name="SMTPAppender"/> + <h3>SMTPAppender</h3> + + <p> + The <code>SMTPAppender</code> accumulates logging events in a fixed-size + buffer and sends them in an email when a user specified triggering event occurs. + By default, the triggering event is taken as the reception of an event + of level <em>ERROR</em> or higher. + </p> + + <p> + The various options for <code>SMTPAppender</code> are summarized in the following table. + </p> + + <table> + <tr> + <th>Option Name</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td><b><span class="option">SMTPHost</span></b></td> + <td><code>String</code></td> + <td> + The host name of the SMTP server. This parameter is mandatory. + </td> + </tr> + <tr> + <td><b><span class="option">To</span></b></td> + <td><code>String</code></td> + <td> + The email address of the recipient. Multiple recipients can + be specified by separating each recipient with a comma. + </td> + </tr> + <tr> + <td><b><span class="option">From</span></b></td> + <td><code>String</code></td> + <td> + The stated originator of the email messages sent by + <code>SMTPAppender</code>. + </td> + </tr> + <tr> + <td><b><span class="option">Subject</span></b></td> + <td><code>String</code></td> + <td> + <p> + The subject of the email. The String can contain a <code>Pattern</code> + that <code>PatternLayout</code> uses. In that case, the subject + is created just before the transmission of the email, with information + about the last logging event that was issued. + </p> + <p> + For example, setting <em>Log: %logger - %msg</em> as the + <span class="option">Subject</span> option will send an email with + the logger name and message string of the event that triggered the + email transmission. + </p> + <p> + By default, <code>SMTPAppender</code> will form a subject with + the message of the last logging event. + </p> + </td> + </tr> + <tr> + <td><b><span class="option">BufferSize</span></b></td> + <td><code>String</code></td> + <td> + The <span class="option">BufferSize</span> option takes a positive + integer representing the maximum number of logging events to collect in a + cyclic buffer. When the <span class="option">BufferSize</span> is reached, + oldest events are deleted as new events are added to the buffer. + The default size of the cyclic buffer is 512. + </td> + </tr> + <tr> + <td><b><span class="option">EvaluatorClass</span></b></td> + <td><code>String</code></td> + <td> + The <span class="option">EvaluatorClass</span> option takes a string + value representing the name of the class implementing the + <code>TriggeringPolicy</code> interface. A corresponding object will be + instantiated and assigned as the triggering event evaluator for the + <code>SMTPAppender</code>. In the absence of this option, + <code>SMTPAppender</code> is assigned a default evaluator which triggers + email transmission as a response to any event of level <em>ERROR</em> or higher. + </td> + </tr> + </table> + + <p> + The SMTPAppender keeps only the last <span class="option">BufferSize</span> logging events + in its cyclic buffer, throwing away older events when its buffer becomes full. + The number of logging events delivered in any e-mail sent by <code>SMTPAppender</code> + is upper-bounded by <span class="option">BufferSize</span>. This keeps memory + requirements bounded while still delivering the desired amount of application context. + </p> + + <p> + The <code>SMTPAppender</code> relies on the JavaMail API. + It has been tested with JavaMail API version 1.4. + The JavaMail API requires the JavaBeans Activation Framework package. + You can download the <a href="http://java.sun.com/products/javamail/">JavaMail API</a> + and the <a href="http://java.sun.com/beans/glasgow/jaf.html">Java-Beans Activation Framework</a> + from their respective websites. + Make sure to place these two jar files in the classpath before + trying the following examples. + </p> + + <p> + A sample application called <code>chapter4.mail.EMail</code> takes two parameters. + The first parameter is an integer corresponding to the number of logging events + to generate. The second parameter is the logback configuration file in XML format. + The last logging event generated by chapter4.mail.Email application is always an + <em>ERROR</em> event which triggers the transmission of an email message. + </p> + + <p> + Here is a sample configuration file you can supply to chapter4.mail.Email: + </p> + +<em>Example 4.3: A sample <code>SMTPAppender</code> configuration (logback-examples/src/main/java/chapter4/mail/mail1.xml)</em> +<div class="source"><pre><configuration> + + <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> + <SMTPHost>ADDRESS-OF-YOUR-SMTP-HOST</SMTPHost> + <To>DESTINATION-EMAIL</To> + <From>SENDER-EMAIL</From> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%date %-5level %logger - %message%n</Pattern> + </layout> + </appender> + + <root> + <level value ="debug"/> + <appender-ref ref="EMAIL" /> + </root> +</configuration></pre></div> + + <p> + Before trying out <code>chapter4.mail.Email</code> application with the above + configuration file, you must set the <span class="option">SMTPHost</span>, + <span class="option">To</span> and <span class="option">From</span> options + to values appropriate for your environment. Once you have set the proper values, + execute the following command: + </p> + +<div class="source"><pre>java chapter4.mail.EMail 300 chapter4/mail/mail.xml</pre></div> + + <p> + The chosen recipient should see an email message containing 300 logging events + formatted by <code>PatternLayout</code>. + </p> + + <p> + In another configuration file <em>mail2.xml</em>, the values for the + <span class="option">SMTPHost</span>, <span class="option">To</span> + and <span class="option">From</span> options are determined by variable + substitution. Here is the relevant part of <em>mail2.xml</em>. + </p> + +<div class="source"><pre> + <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> + <SMTPHost>${smtpHost}</SMTPHost> + <To>${to}</To> + <From>${from}</From> + <layout class="ch.qos.logback.classic.html.HTMLLayout"/> + </appender> +</pre></div> + + <p> + You can supply the various values on the command line: + </p> + +<div class="source"><pre>java -Dfrom=source@xyz.com -Dto=recipient@xyz.com + -DsmtpHost=some_smtp_host chapter4.mail.EMail 10000 chapter4/mail/mail2.xml +</pre></div> + <p> + Be sure to replace with the correct values appropriate for your environment. + </p> + + <p> + Given that the default size of the cyclic buffer is 512, + the recipient should see an email message containing 512 events conveniently + formatted in an HTML table. Note that this run of the <code>chapter4.mail.Email</code> + application generated 10'000 events of which only the last 512 were included in the email. + </p> + + <p> + By default, the <code>SMTPAppender</code> will initiate the transmission of an email + message as a response to an event of level <em>ERROR</em> or higher. + However, it is possible to override this default behavior by providing a custom + implementation of the <code>TriggeringPolicy</code> interface. + </p> + + <p> + The <code>SMTPAppender</code> submits each incoming event to its evaluator + by calling <code>isTriggeringEvent()</code> method in order to check whether + the event should trigger an email or just be placed in the cyclic buffer. + The <code>SMTPAppender</code> contains one and only one evaluator object. + This object may possess its own state. For illustrative purposes, + the <code>CounterBasedTP</code> class listed next, implements a triggering policy whereby + every 1024th event triggers an email message. + </p> +<em>Example 4.4: A <code>TriggeringPolicy</code> implementation +that triggers every 1024th event (<a href="../xref/chapter4/mail/CounterBasedTP.html">logback-examples/src/main/java/chapter4/mail/CounterBasedTP.java</a>)</em> +<div class="source"><pre>package chapter4.mail; +import java.io.File; +import ch.qos.logback.core.rolling.TriggeringPolicyBase; +public class CounterBasedTP extends TriggeringPolicyBase { + boolean started; + static int LIMIT = 1024; + int counter = 0; + + public boolean isTriggeringEvent(File file, Object event) { + counter++; + + if (counter == LIMIT) { + counter = 0; + + return true; + } else { + return false; + } + } +}</pre></div> + <p> + Setting the <span class="option">EvaluatorClass</span> option of + <code>SMTPAppender</code> instructs it to use a custom evaluator. + The next configuration file attaches a <code>SMTPAppender</code> to the root logger. + This appender has a buffer size of 2048 and uses a <code>CounterBasedTP</code> instance + as its triggering event evaluator. + </p> + +<em>Example 4.5: <code>SMTPAppender</code> with custom +<code>TriggeringPolicy</code> and buffer size (logback-examples/src/main/java/chapter4/mail/mail3.xml)</em> + +<div class="source"><pre><configuration> + <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> + <EvaluatorClass>chapter4.mail.CounterBasedTP</EvaluatorClass> + <BufferSize>1050</BufferSize> + <SMTPHost>${smtpHost}</SMTPHost> + <To>${to}</To> + <From>${from}</From> + <layout class="ch.qos.logback.classic.html.HTMLLayout"/> + </appender> + + <root> + <level value ="debug"/> + <appender-ref ref="EMAIL" /> + </root> +</configuration></pre></div> @@ -1392,10 +1641,16 @@ + <h3>DBAppender</h3> + <h3>SyslogAppender</h3> + + <h2>Logback Access</h2> + + <h3>SMTPAppender</h3>