[logback-dev] svn commit: r876 - in logback/trunk: logback-classic/src/main/java/ch/qos/logback/classic/net logback-examples/src/main/java/chapter4/mail logback-examples/src/main/java/chapter4/socket logback-site/src/site/xdocTemplates/manual
noreply.seb at qos.ch
noreply.seb at qos.ch
Mon Nov 6 20:21:29 CET 2006
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 at xyz.com -Dto=recipient at 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>
More information about the logback-dev
mailing list