Chapter 4: Appenders

What is an Appender?

Logback delegates the task of writing a logging event to components called appenders. Appenders must implement the ch.qos.logback.core.Appender interface. The salient methods of this interface are summarized below:

Most of the methods in the Appender interface are setters and getters. A notable exception is the doAppend() method taking an object instance of type E as its only parameter. The actual type of E will vary depending on the logback module. Within the logback-classic module E would be of type ILoggingEvent and within the logback-access module it would be of type AccessEvent. The doAppend() method is perhaps the most important in the logback framework. It is responsible for outputting the logging events in a suitable format to the appropriate output device.

Appenders are named entities. This ensures that they can be referenced by name, a quality confirmed to be instrumental in configuration scripts. The Appender interface extends the FilterAttachable interface. It follows that one or more filters can be attached to an appender instance. Filters are discussed in detail in a subsequent chapter.

Appenders are ultimately responsible for outputting logging events. However, they may delegate the actual formatting of the event to a Layout or to an Encoder object. Each layout/encoder is associated with one and only one appender, referred to as the owning appender. Some appenders have a built-in or fixed event format. Consequently, they do not require nor have a layout/encoder. For example, the SocketAppender simply serializes logging events before transmitting them over the wire.

AppenderBase

The ch.qos.logback.core.​AppenderBase class is an abstract class implementing the Appender interface. It provides basic functionality shared by all appenders, such as methods for getting or setting their name, their activation status, their layout and their filters. It is the super-class of all appenders shipped with logback. Although an abstract class, AppenderBase actually implements the doAppend() method in the Append interface. Perhaps the clearest way to discuss AppenderBase class is by presenting an excerpt of actual source code.

public synchronized void doAppend(E eventObject) {

  // prevent re-entry.
  if (guard) {
    return;
  }

  try {
    guard = true;

    if (!this.started) {
      if (statusRepeatCount++ < ALLOWED_REPEATS) {
        addStatus(new WarnStatus(
            "Attempted to append to non started appender [" + name + "].",this));
      }
      return;
    }

    if (getFilterChainDecision(​eventObject) == FilterReply.DENY) {
      return;
    }
    
    // ok, we now invoke the derived class's implementation of append
    this.append(eventObject);

  } finally {
    guard = false;
  }
}

This implementation of the doAppend() method is synchronized. It follows that logging to the same appender from different threads is safe. While a thread, say T, is executing the doAppend() method, subsequent calls by other threads are queued until T leaves the doAppend() method, ensuring T's exclusive access to the appender.

Since such synchronization is not always appropriate, logback ships with ch.qos.logback.core.UnsynchronizedAppenderBase which is very similar to the AppenderBase class. For the sake of conciseness, we will be discussing UnsynchronizedAppenderBase in the remainder of this document.

The first thing the doAppend() method does is to check whether the guard is set to true. If it is, it immediately exits. If the guard is not set, it is set to true at the next statement. The guard ensures that the doAppend() method will not recursively call itself. Just imagine that a component, called somewhere beyond the append() method, wants to log something. Its call could be directed to the very same appender that just called it resulting in an infinite loop and a stack overflow.

In the following statement we check whether the started field is true. If it is not, doAppend() will send a warning message and return. In other words, once an appender is closed, it is impossible to write to it. Appender objects implement the LifeCycle interface, which implies that they implement start(), stop() and isStarted() methods. After setting all the properties of an appender, Joran, logback's configuration framework, calls the start() method to signal the appender to activate its properties. Depending on its kind, an appender may fail to start if certain properties are missing or because of interference between various properties. For example, given that file creation depends on truncation mode, FileAppender cannot act on the value of its File option until the value of the Append option is also known with certainty. The explicit activation step ensures that an appender acts on its properties after their values become known.

If the appender could not be started or if it has been stopped, a warning message will be issued through logback's internal status management system. After several attempts, in order to avoid flooding the internal status system with copies of the same warning message, the doAppend() method will stop issuing these warnings.

The next if statement checks the result of the attached filters. Depending on the decision resulting from the filter chain, events can be denied or explicitly accepted. In the absence of a decision by the filter chain, events are accepted by default.

The doAppend() method then invokes the derived classes' implementation of the append() method. This method does the actual work of appending the event to the appropriate device.

Finally, the guard is released so as to allow a subsequent invocation of the doAppend() method.

For the remainder of this manual, we reserve the term "option" or alternatively "property" for any attribute that is inferred dynamically using JavaBeans introspection through setter and getter methods.

Logback-core

Logback-core lays the foundation upon which the other logback modules are built. In general, the components in logback-core require some, albeit minimal, customization. However, in the next few sections, we describe several appenders which are ready for use out of the box.

OutputStreamAppender

OutputStreamAppender appends events to a java.io.OutputStream. This class provides basic services that other appenders build upon. Users do not usually instantiate OutputStreamAppender objects directly, since in general the java.io.OutputStream type cannot be conveniently mapped to a string, as there is no way to specify the target OutputStream object in a configuration script. Simply put, you cannot configure a OutputStreamAppender from a configuration file. However, this does not mean that OutputStreamAppender lacks configurable properties. These properties are described next.

The OutputStreamAppender is the super-class of three other appenders, namely ConsoleAppender, FileAppender which in turn is the super class of RollingFileAppender. The next figure illustrates the class diagram for OutputStreamAppender and its subclasses.

ConsoleAppender

The ConsoleAppender, as the name indicates, appends on the console, or more precisely on System.out or System.err, the former being the default target. ConsoleAppender formats events with the help of an encoder specified by the user. Encoders will be discussed in a subsequent chapter. Both System.out and System.err are of type java.io.PrintStream. Consequently, they are wrapped inside an OutputStreamWriter which buffers I/O operations.

WARNING Please note the console is comparatively slow, even very slow. You should avoid logging to the console in production, especially in high volume systems.

Here is a sample configuration that uses ConsoleAppender.

Example: ConsoleAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-Console.​xml)

<configuration>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <!-- encoders are assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} -%kvp- %msg %n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="STDOUT" />
  </root>
  </configuration>
    

After you have set your current path to the logback-examples directory and set up your class path, you can give the above configuration file a whirl by issuing the following command:

java chapters.appenders.​ConfigurationTester src/main/java/chapters/​appenders/conf/​logback-Console.xml

FileAppender

The FileAppender, a subclass of OutputStreamAppender, appends log events into a file. The target file is specified by the File option. If the file already exists, it is either appended to, or truncated depending on the value of the append property.

Immediate Flush By default, each log event is immediately flushed to the underlying output stream. This default approach is safer in the sense that logging events are not lost in case your application exits without properly closing appenders. However, for significantly increased logging throughput, you may want to set the immediateFlush property to false.

Below is an example of a configuration file for FileAppender:

Example: FileAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-fileAppender.​xml)

<configuration>

  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>testFile.log</file>
    <append>true</append>
    <!-- set immediateFlush to false for much higher logging throughput -->
    <immediateFlush>true</immediateFlush>
    <!-- encoders are assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} -%kvp- %msg%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="FILE" />
  </root>
</configuration>

After changing the current directory to logback-examples, run this example by launching the following command:

java chapters.appenders.​ConfigurationTester src/main/java/chapters/​appenders/conf/​logback-fileAppender.​xml

Uniquely named files (by timestamp)

During the application development phase or in the case of short-lived applications, e.g. batch applications, it is desirable to create a new log file at each new application launch. This is fairly easy to do with the help of the <timestamp> element. Here's an example.

Example: Uniquely named FileAppender configuration by timestamp (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-timestamp.​xml)

<configuration>

  <!-- Insert the current time formatted as "yyyyMMdd'T'HHmmss" under
       the key "bySecond" into the logger context. This value will be
       available to all subsequent configuration elements. -->
  <timestamp key="bySecond" datePattern="yyyyMMdd'T'HHmmss"/>

  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <!-- use the previously created timestamp to create a uniquely
         named log file -->
    <file>log-${bySecond}.txt</file>
    <encoder>
      <pattern>%logger{35} -%kvp- %msg%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="FILE" />
  </root>
     </configuration>

The timestamp element takes two mandatory attributes key and datePattern and an optional timeReference attribute. The key attribute is the name of the key under which the timestamp will be available to subsequent configuration elements as a variable. The datePattern attribute denotes the date pattern used to convert the current time (at which the configuration file is parsed) into a string. The date pattern should follow the conventions defined in SimpleDateFormat. The timeReference attribute denotes the time reference for the time stamp. The default is the interpretation/parsing time of the configuration file, i.e. the current time. However, under certain circumstances it might be useful to use the context birth time as time reference. This can be accomplished by setting the timeReference attribute to "contextBirth".

Experiment with the <timestamp> element by running the command:

java chapters.appenders.​ConfigurationTester src/main/resources/​chapters/appenders/​conf/logback-timestamp.​xml

To use the logger context birthdate as time reference, you would set the timeReference attribute to "contextBirth" as shown below.

Example: Timestamp using context birthdate as time reference (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-timestamp-contextBirth.​xml)

<configuration>
  <timestamp key="bySecond" datePattern="yyyyMMdd'T'HHmmss" 
             timeReference="contextBirth"/>
  ...
</configuration>

RollingFileAppender

RollingFileAppender extends FileAppender with the capability to rollover log files. For example, RollingFileAppender can log to a file named log.txt file and, once a certain condition is met, change its logging target to another file.

There are two important subcomponents that interact with RollingFileAppender. The first RollingFileAppender sub-component, namely RollingPolicy, (see below) is responsible for undertaking the actions required for a rollover. A second subcomponent of RollingFileAppender, namely TriggeringPolicy, (see below) will determine if and exactly when rollover occurs. Thus, RollingPolicy is responsible for the what and TriggeringPolicy is responsible for the when.

To be of any use, a RollingFileAppender must have both a RollingPolicy and a TriggeringPolicy set up. However, if its RollingPolicy also implements the TriggeringPolicy interface, then only the former needs to be specified explicitly.

Here are the available properties for RollingFileAppender:

Overview of rolling policies

RollingPolicy is responsible for the rollover procedure which involves file moving and renaming.

The RollingPolicy interface is presented below:

package ch.qos.logback.core.rolling;

import ch.qos.logback.core.FileAppender;
import ch.qos.logback.core.spi.LifeCycle;

public interface RollingPolicy extends LifeCycle {

  public void rollover() throws RolloverFailure;
  public String getActiveFileName();
  public CompressionMode getCompressionMode();
  public void setParent(FileAppender appender);
}

The rollover method accomplishes the work involved in archiving the current log file. The getActiveFileName() method is called to compute the file name of the current log file (where live logs are written to). As indicated by getCompressionMode method a RollingPolicy is also responsible for determining the compression mode. Lastly, a RollingPolicy is given a reference to its parent via the setParent method.

TimeBasedRollingPolicy

TimeBasedRollingPolicy is possibly the most popular rolling policy. It defines a rollover policy based on time, for example by day or by month. TimeBasedRollingPolicy assumes the responsibility for rollover as well as for the triggering of said rollover. Indeed, TimeBasedTriggeringPolicy implements both RollingPolicy and TriggeringPolicy interfaces.

TimeBasedRollingPolicy's configuration takes one mandatory fileNamePattern property and several optional properties.

/var/log/%d{yyyy/MM, aux}/myapplication.%d{yyyy-MM-dd}.log

aFolder/test.%d{yyyy-MM-dd-HH, UTC}.log

Here are a few fileNamePattern values with an explanation of their effects.

Any forward or backward slash characters are interpreted as folder (directory) separators. Any required folder will be created as necessary. You can thus easily place your log files in separate folders.

Automatic file compression

TimeBasedRollingPolicy supports automatic file compression. This feature is enabled if the value of the fileNamePattern option ends with .gz or .zip.

The fileNamePattern serves a dual purpose. First, by studying the pattern, logback computes the requested rollover periodicity. Second, it computes each archived file's name. Note that it is possible for two different patterns to specify the same periodicity. The patterns yyyy-MM and yyyy@MM both specify monthly rollover, although the resulting archive files will carry different names.

By setting the file property you can decouple the location of the active log file and the location of the archived log files. The logging output will be targeted into the file specified by the file property. It follows that the name of the active log file will not change over time. However, if you choose to omit the file property, then the active file will be computed anew for each period based on the value of fileNamePattern. By leaving the file option unset you can avoid file renaming errors which occur while there exist external file handles referencing log files during roll over.

The maxHistory property controls the maximum number of archive files to keep, deleting older files. For example, if you specify monthly rollover, and set maxHistory to 6, then 6 months worth of archives files will be kept with files older than 6 months deleted. Note as old archived log files are removed, any folders which were created for the purpose of log file archiving will be removed as appropriate.

For various technical reasons, rollovers are not clock-driven but depend on the arrival of logging events. For example, on 8th of March 2002, assuming the fileNamePattern is set to yyyy-MM-dd (daily rollover), the arrival of the first event after midnight will trigger a rollover. If there are no logging events during, say 23 minutes and 47 seconds after midnight, then rollover will actually occur at 00:23'47 AM on March 9th and not at 0:00 AM. Thus, depending on the arrival rate of events, rollovers might be triggered with some latency. However, regardless of the delay, the rollover algorithm is known to be correct, in the sense that all logging events generated during a certain period will be output in the correct file delimiting that period.

Here is a sample configuration for RollingFileAppender in conjunction with a TimeBasedRollingPolicy.

Example: Sample configuration of a RollingFileAppender using a TimeBasedRollingPolicy (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-RollingTimeBased.​xml)

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logFile.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <!-- daily rollover -->
      <fileNamePattern>logFile.%d{yyyy-MM-dd}.log</fileNamePattern>

      <!-- keep 30 days' worth of history capped at 3GB total size -->
      <maxHistory>30</maxHistory>
      <totalSizeCap>3GB</totalSizeCap>

    </rollingPolicy>

    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} -%kvp- %msg%n</pattern>
    </encoder>
  </appender> 

  <root level="DEBUG">
    <appender-ref ref="FILE" />
  </root>
</configuration>

The next configuration sample illustrates the use of RollingFileAppender associated with TimeBasedRollingPolicy in prudent mode.

Example: Sample configuration of a RollingFileAppender using a TimeBasedRollingPolicy (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-PrudentTimeBasedRolling.​xml)

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <!-- Support multiple-JVM writing to the same log file -->
    <prudent>true</prudent>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <fileNamePattern>logFile.%d{yyyy-MM-dd}.log</fileNamePattern>
      <maxHistory>30</maxHistory> 
      <totalSizeCap>3GB</totalSizeCap>
    </rollingPolicy>

    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} -%kvp -%msg%n</pattern>
    </encoder>
  </appender> 

  <root level="DEBUG">
    <appender-ref ref="FILE" />
  </root>
</configuration>

Size and time based rolling policy

Sometimes you may wish to archive files essentially by date but at the same time limit the size of each log file, in particular if post-processing tools impose size limits on the log files. In order to address this requirement, logback ships with SizeAndTimeBasedRollingPolicy.

Note that TimeBasedRollingPolicy already allows limiting the combined size of archived log files. If you only wish to limit the combined size of log archives, then TimeBasedRollingPolicy described above and setting the totalSizeCap property should be amply sufficient. Moreover, given that file renaming is a relatively slow process and is frought with problems, we discourage the use of SizeAndTimeBasedRollingPolicy unless you have a real-world use case.

The roll over based on size relies on the "%i" conversion token in addition to "%d". Both the %i and %d tokens are mandatory. Each time the current log file reaches maxFileSize before the current time period ends, it will be archived with an increasing index, starting at 0.

The table below lists the properties applicable for SizeAndTimeBasedRollingPolicy. Note these properties complement those applicable for TimeBasedRollingPolicy.

Here is a sample configuration file demonstrating time and size based log file archiving.

Example: Sample configuration for SizeAndTimeBasedRollingPolicy (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-sizeAndTime.​xml)

<configuration>
  <appender name="ROLLING" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>mylog.txt</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
      <!-- rollover daily -->
      <fileNamePattern>mylog-%d{yyyy-MM-dd}.%i.txt</fileNamePattern>
       <!-- each file should be at most 100MB, keep 60 days worth of history, but at most 20GB -->
       <maxFileSize>100MB</maxFileSize>    
       <maxHistory>60</maxHistory>
       <totalSizeCap>20GB</totalSizeCap>
    </rollingPolicy>
    <encoder>
      <pattern>%msg%n</pattern>
    </encoder>
  </appender>


  <root level="DEBUG">
    <appender-ref ref="ROLLING" />
  </root>

</configuration>

Note the "%i" conversion token in addition to "%d". Both the %i and %d tokens are mandatory. Each time the current log file reaches maxFileSize before the current time period ends, it will be archived with an increasing index, starting at 0.

Size and time based archiving supports deletion of old archive files. You need to specify the number of periods to preserve with the maxHistory property. When your application is stopped and restarted, logging will continue at the correct location, i.e. at the largest index number for the current period.

In versions prior to 1.1.7, this document mentioned a component called SizeAndTimeBasedFNATP. However, given that SizeAndTimeBasedRollingPolicy offers a simpler configuration structure, we no longer document SizeAndTimeBasedFNATP. Moreover, in logback version 1.5.8, SizeAndTimeBasedFNATP was renamed as SizeAndTimeBasedFileNamingAndTriggeringPolicy. Thus, earlier configuration files using SizeAndTimeBasedFNATP will no longer work.

FixedWindowRollingPolicy

Given that file renaming is a relatively slow process and is frought with problems, we consider FixedWindowRollingPolicy as a deprecated policy and do not recommend its use.

When rolling over, FixedWindowRollingPolicy renames files according to a fixed window algorithm as described below.

The fileNamePattern option represents the file name pattern for the archived (rolled over) log files. This option is required and must include an integer token %i somewhere within the pattern.

Here are the available properties for FixedWindowRollingPolicy

Given that the fixed window rolling policy requires as many file renaming operations as the window size, large window sizes are strongly discouraged. When large values are specified by the user, the current implementation will automatically reduce the window size to 20.

Let us go over a more concrete example of the fixed window rollover policy. Suppose that minIndex is set to 1, maxIndex set to 3, fileNamePattern property set to foo%i.log, and that file property is set to foo.log.

The configuration file below gives an example of configuring RollingFileAppender and FixedWindowRollingPolicy. Note that the File option is mandatory even if it contains some of the same information as conveyed with the fileNamePattern option.

Example: Sample configuration of a RollingFileAppender using a FixedWindowRollingPolicy (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-RollingFixedWindow.​xml)

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>test.log</file>

    <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
      <fileNamePattern>tests.%i.log.zip</fileNamePattern>
      <minIndex>1</minIndex>
      <maxIndex>3</maxIndex>
    </rollingPolicy>

    <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
      <maxFileSize>5MB</maxFileSize>
    </triggeringPolicy>
    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} -%kvp -%msg%n</pattern>
    </encoder>
  </appender>
	
  <root level="DEBUG">
    <appender-ref ref="FILE" />
  </root>
</configuration>

Overview of triggering policies

TriggeringPolicy implementations are responsible for instructing the RollingFileAppender when to rollover.

The TriggeringPolicy interface contains only one method.

package ch.qos.logback.core.rolling;

import java.io.File;
import ch.qos.logback.core.spi.LifeCycle;

public interface TriggeringPolicy<E> extends LifeCycle {

  public boolean isTriggeringEvent(final File activeFile, final <E> event);
}

The isTriggeringEvent() method takes as parameters the active file and the logging event currently being processed. The concrete implementation determines whether the rollover should occur or not, based on these parameters.

The most widely-used triggering policy, namely TimeBasedRollingPolicy which also doubles as a rolling policy, was already discussed earlier along with other rolling policies.

SizeBasedTriggeringPolicy

SizeBasedTriggeringPolicy looks at the size of the currently active file. If it grows larger than the specified size, it will signal the owning RollingFileAppender to trigger the rollover of the existing active file.

SizeBasedTriggeringPolicy accepts only one parameter, namely maxFileSize, with a default value of 10 MB.

The maxFileSize option can be specified in bytes, kilobytes, megabytes or gigabytes by suffixing a numeric value with KB, MB and respectively GB. For example, 5000000, 5000KB, 5MB and 2GB are all valid values, with the first three being equivalent.

Here is a sample configuration with a RollingFileAppender in conjunction with SizeBasedTriggeringPolicy triggering rollover when the log file reaches 5MB in size.

Example: Sample configuration of a RollingFileAppender using a SizeBasedTriggeringPolicy (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-RollingSizeBased.​xml)

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>test.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
      <fileNamePattern>test.%i.log.zip</fileNamePattern>
      <minIndex>1</minIndex>
      <maxIndex>3</maxIndex>
    </rollingPolicy>

    <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
      <maxFileSize>5MB</maxFileSize>
    </triggeringPolicy>
    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} -%kvp -%msg%n</pattern>
    </encoder>
  </appender>
	
  <root level="DEBUG">
    <appender-ref ref="FILE" />
  </root>
</configuration>

Logback Classic

While logging events are generic in logback-core, within logback-classic they are always instances of ILoggingEvent. Logback-classic is nothing more than a specialized processing pipeline handling instances of ILoggingEvent.

SocketAppender and SSLSocketAppender

The appenders covered thus far are only able to log to local resources. In contrast, the SocketAppender is designed to log to a remote entity by transmitting serialized ILoggingEvent instances over the wire. When using SocketAppender logging events on the wire are sent in the clear. However, when using SSLSocketAppender, logging events are delivered over a secure channel.

The actual type of the serialized event is LoggingEventVO which implements the ILoggingEvent interface. Nevertheless, remote logging is non-intrusive as far as the logging event is concerned. On the receiving end after deserialization, the event can be logged as if it were generated locally. Multiple SocketAppender instances running on different machines can direct their logging output to a central log server whose format is fixed. SocketAppender does not take an associated layout because it sends serialized events to a remote server. SocketAppender operates above the Transmission Control Protocol (TCP) layer which provides a reliable, sequenced, flow-controlled end-to-end octet stream. Consequently, if the remote server is reachable, then log events will eventually arrive there. Otherwise, if the remote server is down or unreachable, the logging events will simply be dropped. If and when the server comes back up, then event transmission will be resumed transparently. This transparent reconnection is performed by a connector thread which periodically attempts to connect to the server.

Logging events are automatically buffered by the native TCP implementation. This means that if the link to server is slow but still faster than the rate of event production by the client, the client will not be affected by the slow network connection. However, if the network connection is slower than the rate of event production, then the client can only progress at the network rate. In particular, in the extreme case where the network link to the server is down, the client will be eventually blocked. Alternatively, if the network link is up, but the server is down, the client will not be blocked, although the log events will be lost due to server unavailability.

Even if a SocketAppender is no longer attached to any logger, it will not be garbage collected in the presence of a connector thread. A connector thread exists only if the connection to the server is down. To avoid this garbage collection problem, you should close the SocketAppender explicitly. Long-lived applications which create/destroy many SocketAppender instances should be aware of this garbage collection problem. Most other applications can safely ignore it. If the JVM hosting the SocketAppender exits before the SocketAppender is closed, either explicitly or subsequent to garbage collection, then there might be untransmitted data in the pipe which may be lost. This is a common problem on Windows based systems. To avoid lost data, it is usually sufficient to close() the SocketAppender either explicitly or by calling the LoggerContext's stop() method before exiting the application.

The remote server is identified by the remoteHost and port properties. SocketAppender properties are listed in the following table. SSLSocketAppender supports many additional configuration properties, which are detailed in the section entitled Using SSL.

Logging Server Options

The standard Logback Classic distribution includes two options for servers that can be used to receive logging events from SocketAppender or SSLSocketAppender.

• ServerSocketReceiver and its SSL-enabled counterpart SSLServerSocketReceiver are receiver components which can be configured in the logback.xml configuration file of an application in order receive events from a remote socket appender. See Receivers for configuration details and usage examples.
• SimpleSocketServer and its SSL-enabled counterpart SimpleSSLSocketServer both offer an easy-to-use standalone Java application that is designed to be configured and run from your shell's command line interface. These applications simply wait for logging events from SocketAppender or SSLSocketAppender clients. Each received event is logged according to local server policy. Usage examples are given below.

Using SimpleSocketServer

The SimpleSocketServer application takes two command-line arguments: port and configFile; where port is the port to listen on and configFile is a configuration script in XML format.

Assuming you are in the logback-examples/ directory, start SimpleSocketServer with the following command:

java ch.qos.logback.classic.​net.SimpleSocketServer 6000 \ src/main/java/chapters/​appenders/socket/​server1.xml

where 6000 is the port number to listen on and server1.xml is a configuration script that adds a ConsoleAppender and a RollingFileAppender to the root logger. After you have started SimpleSocketServer, you can send it log events from multiple clients using SocketAppender. The examples associated with this manual include two such clients: chapters.appenders.​SocketClient1 and chapters.appenders.​SocketClient2 Both clients wait for the user to type a line of text on the console. The text is encapsulated in a logging event of level debug and then sent to the remote server. The two clients differ in the configuration of the SocketAppender. SocketClient1 configures the appender programmatically while SocketClient2 requires a configuration file.

Assuming SimpleSocketServer is running on the local host, you connect to it with the following command:

java chapters.appenders.socket.SocketClient1 localhost 6000

Each line that you type should appear on the console of the SimpleSocketServer launched in the previous step. If you stop and restart the SimpleSocketServer the client will transparently reconnect to the new server instance, although the events generated while disconnected will be simply (and irrevocably) lost.

Unlike SocketClient1, the sample application SocketClient2 does not configure logback by itself. It requires a configuration file in XML format. The configuration file client1.xml shown below creates a SocketAppender and attaches it to the root logger.

Example: SocketAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​socket/client1.​xml)

<configuration>
	  
  <appender name="SOCKET" class="ch.qos.logback.classic.net.SocketAppender">
    <remoteHost>${host}</remoteHost>
    <port>${port}</port>
    <reconnectionDelay>10000</reconnectionDelay>
    <includeCallerData>${includeCallerData}</includeCallerData>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="SOCKET" />
  </root>  

</configuration>

Note that in the above configuration scripts the values for the remoteHost, port and includeCallerData properties are not given directly but as substituted variable keys. The values for the variables can be specified as system properties:

java -Dhost=localhost -Dport=6000 -DincludeCallerData=false \ chapters.appenders.socket.SocketClient2 src/main/java/chapters/​appenders/socket/​client1.xml

This command should give similar results to the previous SocketClient1 example.

Allow us to repeat for emphasis that serialization of logging events is not intrusive. A deserialized event carries the same information as any other logging event. It can be manipulated as if it were generated locally; except that serialized logging events by default do not include caller data. Here is an example to illustrate the point. First, start SimpleSocketServer with the following command:

java ch.qos.logback.classic.​net.SimpleSocketServer 6000 \ src/main/java/chapters/​appenders/socket/​server2.xml

The configuration file server2.xml creates a ConsoleAppender whose layout outputs the caller's file name and line number along with other information. If you run SocketClient2 with the configuration file client1.xml as previously, you will notice that the output on the server side will contain two question marks between parentheses instead of the file name and the line number of the caller:

2006-11-06 17:37:30,968 DEBUG [Thread-0] [?:?] chapters.appenders.​socket.SocketClient2 - Hi

The outcome can be easily changed by instructing the SocketAppender to include caller data by setting the includeCallerData option to true. Using the following command will do the trick:

java -Dhost=localhost -Dport=6000 -DincludeCallerData=true \
  chapters.appenders.socket.SocketClient2 src/main/java/chapters/​appenders/socket/​client1.xml

As deserialized events can be handled in the same way as locally generated events, they even can be sent to a second server for further treatment. As an exercise, you may wish to set up two servers where the first server tunnels the events it receives from its clients to a second server.

Using SimpleSSLSocketServer

The SimpleSSLSocketServer requires the same port and configFile command-line arguments used by SimpleSocketServer. Additionally, you must provide the location and password for your logging server's X.509 credential using system properties specified on the command line.

Assuming you are in the logback-examples/ directory, start SimpleSSLSocketServer with the following command:

java -Djavax.net.ssl.​keyStore=src/main/​java/chapters/appenders/​socket/ssl/keystore.​jks \ -Djavax.net.ssl.​keyStorePassword=​changeit \ ch.qos.logback.classic.​net.SimpleSSLSocketServer 6000 \ src/main/java/chapters/​appenders/socket/​ssl/server.xml

This example runs SimpleSSLSocketServer using an X.509 credential that is suitable for testing and experimentation, only. Before using SimpleSSLSocketServer in a production setting you should obtain an appropriate X.509 credential to identify your logging server. See Using SSL for more details.

Because the server configuration has debug="true" specified on the root element, you will see in the server's startup logging the SSL configuration that will be used. This is useful in validating that local security policies are properly implemented.

With SimpleSSLSocketServer running, you can connect to the server using an SSLSocketAppender. The following example shows the appender configuration needed:

Example: SSLSocketAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​socket/ssl/client.​xml)

<configuration debug="true">
	  
  <appender name="SOCKET" class="ch.qos.logback.classic.net.SSLSocketAppender">
    <remoteHost>${host}</remoteHost>
    <port>${port}</port>
    <reconnectionDelay>10000</reconnectionDelay>
    <ssl>
      <trustStore>
        <location>${truststore}</location>
        <password>${password}</password>
      </trustStore>
    </ssl>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="SOCKET" />
  </root>  

</configuration>

Note that, just as in the previous example, the values for remoteHost, port are specified using substituted variable keys. Additionally, note the presence of the ssl property and its nested trustStore property, which specifies the location and password of a trust store using substituted variables. This configuration is necessary because our example server is using a self-signed certificate. See Using SSL for more information on SSL configuration properties for SSLSocketAppender.

We can run a client application using this configuration by specifying the substitution variable values on the command line as system properties:

java -Dhost=localhost -Dport=6000 \ -Dtruststore=file:src/​main/java/chapters/​appenders/socket/​ssl/truststore.​jks \ -Dpassword=changeit \ chapters.appenders.​socket.SocketClient2 src/main/java/chapters/​appenders/socket/​ssl/client.xml

As in the previous examples, you can type in a message when prompted by the client application, and the message will be delivered to the logging server (now over a secure channel) where it will be displayed on the console.

Note that the truststore property given on the command line specifies a file URL that identifies the location of the trust store. You may also use a classpath URL as described in Using SSL.

As we saw previously at server startup, because the client configuration has debug="true" specified on the root element, the client's startup logging includes the details of the SSL configuration as aid to auditing local policy conformance.

ServerSocketAppender and SSLServerSocketAppender

The SocketAppender component (and its SSL-enabled counterpart) discussed previously are designed to allow an application to connect to a remote logging server over the network for the purpose of delivering logging events to the server. In some situations, it may be inconvenient or infeasible to have an application initiate a connection to a remote logging server. For these situations, Logback offers ServerSocketAppender.

Instead of initiating a connection to a remote logging server, ServerSocketAppender passively listens on a TCP socket awaiting incoming connections from remote clients. Logging events that are delivered to the appender are distributed to each connected client. Logging events that occur when no client is connected are summarily discarded.

In addition to the basic ServerSocketAppender, Logback offers SSLServerSocketAppender, which distributes logging events to each connected client using a secure, encrypted channel. Moreover, the SSL-enabled appender fully supports mutual certificate-based authentication, which can be used to ensure that only authorized clients can connect to the appender to receive logging events.

The approach to encoding logging events for transmission on the wire is identical to that used by SocketAppender; each event is a serialized instance of ILoggingEvent. Only the direction of connection initiation is reversed. While SocketAppender acts as the active peer in establishing the connection to a logging server, ServerSocketAppender is passive; it listens for incoming connections from clients.

The ServerSocketAppender subtypes are intended to be used exclusively with Logback receiver components. See Receivers for additional information on this component type.

The following configuration properties are supported by ServerSocketAppender:

The following example illustrates a configuration that uses ServerSocketAppender:

Example: Basic ServerSocketAppender Configuration (logback-examples/​src/main/resources/​chapters/appenders/​socket/server4.​xml)

<configuration debug="true">
  <appender name="SERVER" 
    class="ch.qos.logback.classic.net.server.ServerSocketAppender">
    <port>${port}</port>
    <includeCallerData>${includeCallerData}</includeCallerData>
  </appender>

  <root level="debug">
    <appender-ref ref="SERVER" />
  </root>  

</configuration>

Note that this configuration differs from previous examples using SocketAppender only in the class specified for the appender, and in the absence of the remoteHost property — this appender waits passively for inbound connections from remote hosts rather than opening a connection to a remote logging server.

The following example illustrates a configuration using SSLServerSocketAppender.

Example: Basic SSLServerSocketAppender Configuration (logback-examples/​src/main/resources/​chapters/appenders/​socket/ssl/server3.​xml)

<configuration debug="true">
  <appender name="SERVER" 
    class="ch.qos.logback.classic.net.server.SSLServerSocketAppender">
    <port>${port}</port>
    <includeCallerData>${includeCallerData}</includeCallerData>
    <ssl>
      <keyStore>
        <location>${keystore}</location>
        <password>${password}</password>
      </keyStore>
    </ssl>
  </appender>

  <root level="debug">
    <appender-ref ref="SERVER" />
  </root>  

</configuration>

The principal differences between this configuration and the previous configuration is that the appender's class attribute identifies the SSLServerSocketAppender type, and the presence of the nested ssl element which specifies, in this example, configuration of a key store containing an X.509 credential for the appender. See Using SSL for information regarding SSL configuration properties.

Because the ServerSocketAppender subtypes are designed to be used with receiver components, we will defer presenting illustrative examples to the chapter entitled Receivers.

SMTPAppender

The SMTPAppender accumulates logging events in one or more fixed-size buffers and sends the contents of the appropriate buffer in an email after a user-specified event occurs. SMTP email transmission (sending) is performed asynchronously. By default, the email transmission is triggered by a logging event of level ERROR. Moreover, by default, a single buffer is used for all events.

The various properties for SMTPAppender are summarized in the following table.

The SMTPAppender keeps only the last 256 logging events in its cyclic buffer, throwing away older events when its buffer becomes full. Thus, the number of logging events delivered in any e-mail sent by SMTPAppender is upper-bounded by 256. This keeps memory requirements bounded while still delivering a reasonable amount of application context.

The SMTPAppender 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 JavaMail API and the JavaBeans Activation Framework from their respective websites. Make sure to place these two jar files in the classpath before trying the following examples.

A sample application, chapters.appenders.mail.EMail generates a number of log messages followed by a single error message. It 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. The last logging event generated by EMail application, an ERROR, will trigger the transmission of an email message.

Here is a sample configuration file intended for the Email application:

Example: A sample SMTPAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​mail/mail1.xml)

<configuration>	  
  <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
    <smtpHost>ADDRESS-OF-YOUR-SMTP-HOST</smtpHost>
    <to>EMAIL-DESTINATION</to>
    <to>ANOTHER_EMAIL_DESTINATION</to> <!-- additional destinations are possible -->
    <from>SENDER-EMAIL</from>
    <subject>TESTING: %logger{20} - %m</subject>
    <layout class="ch.qos.logback.classic.PatternLayout">
      <pattern>%date %-5level %logger{35} - %message%n</pattern>
    </layout>	    
  </appender>

  <root level="DEBUG">
    <appender-ref ref="EMAIL" />
  </root>  
</configuration>

Before trying out chapters.appenders.​mail.Email application with the above configuration file, you must set the smtpHost, to and from properties to values appropriate for your environment. Once you have set the correct values in the configuration file, execute the following command:

The recipient you specified should receive an email message containing 100 logging events formatted by PatternLayout The figure below is the resulting email message as shown by Mozilla Thunderbird.

In the next example configuration file mail2.xml, the values for the smtpHost, to and from properties are determined by variable substitution. Here is the relevant part of mail2.xml.

<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>

You can pass the required parameters on the command line:

java [email protected] [email protected] -DsmtpHost=some_smtp_host \
  chapters.appenders.​mail.EMail 10000 src/main/java/chapters/​appenders/mail/​mail2.xml

Be sure to replace with values as appropriate for your environment.

Note that in this latest example, PatternLayout was replaced by HTMLLayout which formats logs as an HTML table. You can change the list and order of columns as well as the CSS of the table. Please refer to HTMLLayout documentation for further details.

Given that the size of the cyclic buffer is 256, the recipient should see an email message containing 256 events conveniently formatted in an HTML table. Note that this run of the chapters.appenders.​mail.Email application generated 10'000 events of which only the last 256 were included in the outgoing email.

Email clients such as Mozilla Thunderbird, Eudora or MS Outlook, offer reasonably good CSS support for HTML email. However, they sometimes automatically downgrade HTML to plaintext. For example, to view HTML email in Thunderbird, the "View→Message Body As→Original HTML" option must be set. Yahoo! Mail's support for HTML email, in particular its CSS support is very good. Gmail on the other hand, while it honors the basic HTML table structure, ignores the internal CSS formatting. Gmail supports inline CSS formatting but since inline CSS would make the resulting output too voluminous, HTMLLayout does not use inline CSS.

Custom buffer size

By default, the outgoing message will contain the last 256 messages seen by SMTPAppender. If your heart so desires, you may set a different buffer size as shown in the next example.

Example: SMTPAppender configuration with a custom buffer size (logback-examples/​src/main/resources/​chapters/appenders/​mail/customBufferSize.​xml)

<configuration>   
  <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
    <smtpHost>${smtpHost}</smtpHost>
    <to>${to}</to>
    <from>${from}</from>
    <subject>%logger{20} - %m</subject>
    <layout class="ch.qos.logback.classic.html.HTMLLayout"/>

    <cyclicBufferTracker class="ch.qos.logback.core.spi.CyclicBufferTracker">
      <!-- send just one log entry per email -->
      <bufferSize>1</bufferSize>
    </cyclicBufferTracker>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="EMAIL" />
  </root>  
</configuration>    

Triggering event

If the Evaluator property is not set, the SMTPAppender defaults to an OnErrorEvaluator instance which triggers email transmission when it encounters an event of level ERROR. While triggering an outgoing email in response to an error is relatively reasonable, it is possible to override this default behavior by providing a different implementation of the EventEvaluator interface.

The SMTPAppender submits each incoming event to its evaluator by calling evaluate() method in order to check whether the event should trigger an email or just be placed in the cyclic buffer. When the evaluator gives a positive answer to its evaluation, an email is sent out. The SMTPAppender contains one and only one evaluator object. This object may manage its own internal state. For illustrative purposes, the CounterBasedEvaluator class listed next implements an event evaluator whereby every 1024th event triggers an email message.

Example: A EventEvaluator implementation that evaluates to true every 1024th event (logback-examples/src/main/java/chapters/appenders/mail/CounterBasedEvaluator.java)

package chapters.appenders.mail;

import ch.qos.logback.core.boolex.EvaluationException;
import ch.qos.logback.core.boolex.EventEvaluator;
import ch.qos.logback.core.spi.ContextAwareBase;

public class CounterBasedEvaluator extends ContextAwareBase implements EventEvaluator {

  static int LIMIT = 1024;
  int counter = 0;
  String name;

  public boolean evaluate(Object event) throws NullPointerException,
      EvaluationException {
    counter++;

    if (counter == LIMIT) {
      counter = 0;

      return true;
    } else {
      return false;
    }
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }
}

Note that this class extends ContextAwareBase and implements EventEvaluator. This allows the user to concentrate on the core functions of her EventEvaluator and let the base class provide the common functionality.

Setting the Evaluator option of SMTPAppender instructs it to use a custom evaluator. The next configuration file attaches a SMTPAppender to the root logger. This appender uses a CounterBasedEvaluator instance as its event evaluator.

Example: SMTPAppender with custom Evaluator and buffer size (logback-examples/​src/main/resources/​chapters/appenders/​mail/mail3.xml)

<configuration>
  <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
    <evaluator class="chapters.appenders.mail.CounterBasedEvaluator" />
    <smtpHost>${smtpHost}</smtpHost>
    <to>${to}</to>
    <from>${from}</from>
    <subject>%logger{20} - %m</subject>

    <layout class="ch.qos.logback.classic.html.HTMLLayout"/>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="EMAIL" />
  </root>  
</configuration>

Marker based triggering

Although reasonable, the default triggering policy whereby every event of level ERROR triggers an outgoing email may result in too many emails, cluttering the targeted user's mailbox. Logback ships with another triggering policy, called OnMarkerEvaluator. It is based on markers. In essence, emails are triggered only if the event is marked with a user-specified marker. The next example should make the point clearer.

The Marked_EMail application contains several logging statements some of which are of level ERROR. One noteworthy statement contains a marker. Here is the relevant code.

Marker notifyAdmin = MarkerFactory.getMarker("NOTIFY_ADMIN");
logger.error(notifyAdmin,
  "This is a serious error requiring the admin's attention",
   new Exception("Just testing"));

The next configuration file will trigger outgoing emails only in presence of events bearing the NOTIFY_ADMIN or the TRANSACTION_FAILURE markers.

Example: SMTPAppender with OnMarkerEvaluator (logback-examples/​src/main/resources/​chapters/appenders/​mail/mailWithMarker.​xml)

<configuration>
  <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
    <evaluator class="ch.qos.logback.classic.boolex.OnMarkerEvaluator">
      <marker>NOTIFY_ADMIN</marker>
      <!-- you specify add as many markers as you want -->
      <marker>TRANSACTION_FAILURE</marker>
    </evaluator>
    <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>

Give it a whirl with the following command:

java [email protected] [email protected] -DsmtpHost=some_smtp_host \
  chapters.appenders.​mail.Marked_EMail src/main/java/chapters/​appenders/mail/​mailWithMarker.​xml

Marker-based triggering with JaninoEventEvaluator

Note that instead of using the marker-centric OnMarkerEvaluator, we could use the much more generic JaninoEventEvaluator. For example, the following configuration file uses JaninoEventEvaluator instead of OnMarkerEvaluator but is otherwise equivalent to the previous configuration file.

Example: SMTPAppender with JaninoEventEvaluator (logback-examples/​src/main/resources/​chapters/appenders/​mail/mailWithMarker_Janino.​xml)

<configuration>
  <appender name="EMAIL" class="ch.qos.logback.​classic.net.SMTPAppender">
    <evaluator class="ch.qos.logback.​classic.boolex.​JaninoEventEvaluator">
      <expression>
        (markerList.contains(​"NOTIFY_ADMIN") || marker.contains(​"TRANSACTION_FAILURE"))
      </expression>
    </evaluator>
    <smtpHost>${smtpHost}</smtpHost>
    <to>${to}</to>
    <from>${from}</from>
    <layout class="ch.qos.logback.​classic.html.HTMLLayout"/>
  </appender>
</configuration>

Authentication/STARTTLS/SSL

SMTPAppender supports authentication via plain user passwords as well as both the STARTTLS and SSL protocols. Note that STARTTLS differs from SSL in that, in STARTTLS, the connection is initially non-encrypted and only after the STARTTLS command is issued by the client (if the server supports it) does the connection switch to SSL. In SSL mode, the connection is encrypted right from the start.

SMTPAppender configuration for Gmail (SSL)

The next example shows you how to configure SMTPAppender for Gmail with the SSL protocol.

Example:: SMTPAppender to Gmail using SSL (logback-examples/​src/main/resources/​chapters/appenders/​mail/gmailSSL.xml)

<configuration>
  <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
    <smtpHost>smtp.gmail.com</smtpHost>
    <smtpPort>465</smtpPort>
    <SSL>true</SSL>
    <username>[email protected]</username>
    <password>YOUR_GMAIL_PASSWORD</password>

    <to>EMAIL-DESTINATION</to>
    <to>ANOTHER_EMAIL_DESTINATION</to> <!-- additional destinations are possible -->
    <from>[email protected]</from>
    <subject>TESTING: %logger{20} - %m</subject>
    <layout class="ch.qos.logback.classic.PatternLayout">
      <pattern>%date %-5level %logger{35} - %message%n</pattern>
    </layout>	    
  </appender>

  <root level="DEBUG">
    <appender-ref ref="EMAIL" />
  </root>  
</configuration>

SMTPAppender for Gmail (STARTTLS)

The next example shows you how to configure SMTPAppender for Gmail for the STARTTLS protocol.

Example: SMTPAppender to GMAIL using STARTTLS (logback-examples/​src/main/resources/​chapters/appenders/​mail/gmailSTARTTLS.​xml)

<configuration>
  <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
    <smtpHost>smtp.gmail.com</smtpHost>
    <smtpPort>587</smtpPort>
    <STARTTLS>true</STARTTLS>
    <username>[email protected]</username>
    <password>YOUR_GMAIL_xPASSWORD</password>
    
    <to>EMAIL-DESTINATION</to>
    <to>ANOTHER_EMAIL_DESTINATION</to> <!-- additional destinations are possible -->
    <from>[email protected]</from>
    <subject>TESTING: %logger{20} - %m</subject>
    <layout class="ch.qos.logback.classic.PatternLayout">
      <pattern>%date %-5level %logger - %message%n</pattern>
    </layout>	    
  </appender>

  <root level="DEBUG">
    <appender-ref ref="EMAIL" />
  </root>  
</configuration>

SMTPAppender with MDCDiscriminator

As mentioned earlier, by specifying a discriminator other than the default one, SMTPAppender will generate email messages containing events pertaining to a particular user, user session or client IP address, depending on the specified discriminator.

The next example illustrates the use of MDCBasedDiscriminator in conjunction with the MDC key named "req.remoteHost", assumed to contain the IP address of the remote host accessing a fictitious application. In a web-application, you could use MDCInsertingServletFilter to populate MDC values.

Example: SMTPAppender with MDCBasedDiscriminator (logback-examples/​src/main/resources/​chapters/appenders/​mail/mailWithMDCBasedDiscriminator.​xml)

<configuration>	  
  <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
    <smtpHost>ADDRESS-OF-YOUR-SMTP-HOST</smtpHost>
    <to>EMAIL-DESTINATION</to>
    <from>SENDER-EMAIL</from>

    <discriminator class="ch.qos.logback.classic.sift.MDCBasedDiscriminator">
      <key>req.remoteHost</key>
      <defaultValue>default</defaultValue>
    </discriminator>

    <subject>${HOSTNAME} -- %X{req.remoteHost} %msg"</subject>
    <layout class="ch.qos.logback.classic.html.HTMLLayout">
      <pattern>%date%level%thread%X{req.remoteHost}%X{req.requestURL}%logger%msg</pattern>
    </layout>
  </appender>

  <root>
    <level level="DEBUG"/>
    <appender-ref ref="EMAIL" />
  </root>  
</configuration>

Thus, each outgoing email generated by SMTPAppender will belong to a unique remote host, greatly facilitating problem diagnosis.

Buffer management in very busy systems

Internally, each distinct value returned by the discriminator will cause the creation of a new cyclic buffer. However, at most maxNumberOfBuffers (by default 64) will be maintained. Whenever the number of buffers rises above maxNumberOfBuffers, the least recently updated buffer is automatically discarded. As a second safety measure, any buffer which has not been updated in the last 30 minutes will be automatically discarded as well.

On systems serving a large number of transactions per minute, allowing only a small number for maxNumberOfBuffers (by default 64) will often cause the number of events in the outgoing email to be unnecessarily small. Indeed, in the presence of a large number of transactions, there will be more than one buffer associated with the same transaction as buffers will be killed and re-born in succession for the same discriminator value (or transaction). Note that in even such very busy systems, the maximum number of cyclic buffers is capped by maxNumberOfBuffers.

To avoid such yo-yo effects, SMTPAppender will release the buffer associated with a given discriminator key as soon as it sees an event marked as "FINALIZE_SESSION". This will cause the appropriate buffer to be discarded at the end of each transaction. You can then safely increase the value of maxNumberOfBuffers to a larger value such as 512 or 1024 without risking running out of memory.

There are three distinct but complementary mechanisms working together to manage cyclic buffers. They ensure that only relevant buffers are kept alive at any given moment, even in very busy systems.

DBAppender

The DBAppender inserts logging events into three database tables in a format independent of the Java programming language.

As of logback version 1.2.8 DBAppender no longer ships with logback-classic. However, DBAppender for logback-classic is available under the following Maven coordinates:

ch.qos.logback.db:logback-classic-db:1.​2.11.1

These three tables are logging_event, logging_event_property and logging_event_exception. They must exist before DBAppender can be used. Logback ships with SQL scripts that will create the tables. They can be found under the logback-classic/​src/main/java/ch/​qos/logback/classic/​db/script folder. There is a specific script for each of the most popular database systems. If the script for your particular type of database system is missing, it should be quite easy to write one, taking example on the already existing scripts. If you send them to us, we will gladly include missing scripts in future releases.

If your JDBC driver supports the getGeneratedKeys method introduced in JDBC 3.0 specification, assuming you have created the appropriate database tables as mentioned above, then no additional steps are required. Otherwise, there must be an SQLDialect appropriate for your database system. Currently, logback has dialects for H2, HSQL, MS SQL Server, MySQL, Oracle, PostgreSQL, SQLLite and Sybase.

The table below summarizes the database types and their support of the getGeneratedKeys() method.

Experiments show that writing a single event into the database takes approximately 10 milliseconds, on a "standard" PC. If pooled connections are used, this figure drops to around 1 millisecond. Note that most JDBC drivers already ship with connection pooling support.

Configuring logback to use DBAppender can be done in several different ways, depending on the tools one has to connect to the database, and the database itself. The key issue in configuring DBAppender is about setting its ConnectionSource object, as we shall discover shortly.

Once DBAppender is configured for your database, logging events are sent to the specified database. As stated previously, there are three tables used by logback to store logging event data.

The logging_event table contains the following fields:

The logging_event_property is used to store the keys and values contained in the MDC or the Context. It contains these fields:

The logging_event_exception table contains the following fields:

To give a more visual example of the work done by DBAppender, here is a screenshot of a MySQL database with content provided by DBAppender.

The logging_event table:

The logging_event_exception table:

The logging_event_property table:

ConnectionSource

The ConnectionSource interface provides a pluggable means of transparently obtaining JDBC connections for logback classes that require the use of a java.sql.Connection. There are currently three implementations of ConnectionSource, namely DataSourceConnectionSource, DriverManagerConnectionSource and JNDIConnectionSource.

The first example that we will review is a configuration using DriverManagerConnectionSource and a MySQL database. The following configuration file is what one would need.

Example: DBAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​db/append-toMySQL-with-driverManager.​xml)

<configuration>

  <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
    <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource">
      <driverClass>com.mysql.jdbc.Driver</driverClass>
      <url>jdbc:mysql://host_name:3306/database_name</url>
      <user>username</user>
      <password>password</password>
    </connectionSource>
  </appender>
  
  <root level="DEBUG" >
    <appender-ref ref="DB" />
  </root>
</configuration>

The correct driver must be declared. Here, the com.mysql.jdbc.Driver class is used. The url must begin with jdbc:mysql://.

The DriverManagerConnectionSource is an implementation of ConnectionSource that obtains the connection in the traditional JDBC manner based on the connection URL.

Note that this class will establish a new Connection for each call to getConnection(). It is recommended that you either use a JDBC driver that natively supports connection pooling or that you create your own implementation of ConnectionSource that taps into whatever pooling mechanism you are already using. If you have access to a JNDI implementation that supports javax.sql.DataSource, e.g. within a J2EE application server, see JNDIConnectionSource below.

Connecting to a database using a DataSource is rather similar. The configuration now uses DataSourceConnectionSource, which is an implementation of ConnectionSource that obtains the Connection in the recommended JDBC manner based on a javax.sql.DataSource.

Example: DBAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​db/append-with-datasource.​xml)

<configuration  debug="true">

  <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
     <connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
       
       <dataSource class="${dataSourceClass}">
       	 <!-- Joran cannot substitute variables
       	 that are not attribute values. Therefore, we cannot
       	 declare the next parameter like the others. 
       	 -->
         <param name="${url-key:-url}" value="${url_value}"/>
         <serverName>${serverName}</serverName>
         <databaseName>${databaseName}</databaseName>
       </dataSource>
       
       <user>${user}</user>
       <password>${password}</password>
     </connectionSource>
  </appender>

  <root level="INFO">
    <appender-ref ref="DB" />
  </root>  
</configuration>

Note that in this configuration sample, we make heavy use of substitution variables. They are sometimes handy when connection details have to be centralized in a single configuration file and shared by logback and other frameworks.

JNDIConnectionSource

JNDIConnectionSource is another ConnectionSource implementation shipping in logback. As its name indicates, it retrieves a javax.sql.DataSource from a JNDI and then leverages it to obtain a java.sql.Connection instance. JNDIConnectionSource is primarily designed to be used inside J2EE application servers or by application server clients, assuming the application server supports remote access of javax.sql.DataSource. Thus, one can take advantage of connection pooling and whatever other goodies the application server provides. More importantly, your application will be dryer as it will be no longer necessary to define a DataSource in logback.xml.

For example, here is a configuration snippet for Tomcat. It assumes PostgreSQL as the database although any of the supported database systems (listed above) would work.

<Context docBase="/path/to/app.war" path="/myapp">
  ...
  <Resource name="jdbc/logging"
               auth="Container"
               type="javax.sql.DataSource"
               username="..."
               password="..."
               driverClassName="org.postgresql.Driver"
               url="jdbc:postgresql://localhost/..."
               maxActive="8"
               maxIdle="4"/>
  ...
</Context>

Once a DataSource is defined in the J2EE server, it can be easily referenced by your logback configuration file, as shown in the next example.

Example: DBAppender configuration by JNDIConnectionSource (logback-examples/​src/main/resources/​chapters/appenders/​db/append-via-jndi.​xml)

<configuration debug="true">
  <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
    <connectionSource class="ch.qos.logback.core.db.JNDIConnectionSource">
      <!-- please note the "java:comp/env/" prefix -->
      <jndiLocation>java:comp/env/jdbc/logging</jndiLocation>
    </connectionSource>
  </appender>
  <root level="INFO">
    <appender-ref ref="DB" />
  </root>  
</configuration>

Note that this class will obtain an javax.naming.InitialContext using the no-argument constructor. This will usually work when executing within a J2EE environment. When outside the J2EE environment, make sure that you provide a jndi.properties file as described by your JNDI provider's documentation.

Connection pooling

Logging events can be created at a rather fast pace. To keep up with the flow of events that must be inserted into a database, it is recommended to use connection pooling with DBAppender.

Experiment shows that using connection pooling with DBAppender gives a big performance boost. With the following configuration file, logging events are sent to a MySQL database, without any pooling.

Example: DBAppender configuration without pooling (logback-examples/​src/main/resources/​chapters/appenders/​db/append-toMySQL-with-datasource.​xml)

<configuration>

  <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
    <connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
      <dataSource class="com.mysql.jdbc.jdbc2.optional.MysqlDataSource">
        <serverName>${serverName}</serverName>
        <port>${port$</port>
        <databaseName>${dbName}</databaseName>
        <user>${user}</user>
        <password>${pass}</password>
      </dataSource>
    </connectionSource>
  </appender>
    
  <root level="DEBUG">
    <appender-ref ref="DB" />
  </root>
</configuration>

With this configuration file, sending 500 logging events to a MySQL database takes a whopping 5 seconds, that is 10 milliseconds per request. This figure is unacceptable when dealing with large applications.

A dedicated external library is necessary to use connection pooling with DBAppender. The next example uses c3p0. To be able to use c3p0, one must download it and place c3p0-VERSION.jar in the classpath.

Example: DBAppender configuration with pooling (logback-examples/​src/main/resources/​chapters/appenders/​db/append-toMySQL-with-datasource-and-pooling.​xml)

<configuration>

  <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
    <connectionSource
      class="ch.qos.logback.core.db.DataSourceConnectionSource">
      <dataSource
        class="com.mchange.v2.c3p0.ComboPooledDataSource">
        <driverClass>com.mysql.jdbc.Driver</driverClass>
        <jdbcUrl>jdbc:mysql://${serverName}:${port}/${dbName}</jdbcUrl>
        <user>${user}</user>
        <password>${password}</password>
      </dataSource>
    </connectionSource>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="DB" />
  </root>
</configuration>

With this new configuration, sending 500 logging requests to the aforementioned MySQL database takes around 0.5 seconds, for an average of 1 millisecond per request, that is a tenfold improvement in performance.

SyslogAppender

The syslog protocol is a very simple protocol: a syslog sender sends a small message to a syslog receiver. The receiver is commonly called syslog daemon or syslog server. Logback can send messages to a remote syslog daemon. This is achieved by using SyslogAppender.

Here are the properties you can pass to a SyslogAppender.

The syslog severity of a logging event is converted from the level of the logging event. The DEBUG level is converted to 7, INFO is converted to 6, WARN is converted to 4 and ERROR is converted to 3.

Since the format of a syslog request follows rather strict rules, there is no layout to be used with SyslogAppender. However, using the suffixPattern option lets the user display whatever information she wishes.

Here is a sample configuration using a SyslogAppender.

Example: SyslogAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-syslog.​xml)

<configuration>

  <appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender">
    <syslogHost>remote_home</syslogHost>
    <facility>AUTH</facility>
    <suffixPattern>[%thread] %logger %msg</suffixPattern>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="SYSLOG" />
  </root>
</configuration>

When testing this configuration, you should verify that the remote syslog daemon accepts requests from an external source. Experience shows that, by default, syslog daemons usually deny requests coming via a network connection.

SiftingAppender

As its name implies, a SiftingAppender can be used to separate (or sift) logging according to a given runtime attribute. For example, SiftingAppender can separate logging events according to user sessions, so that the logs generated by different users go into distinct log files, one log file per user.

SiftingAppender achieves this feat by creating nested appenders on the fly. Nested appenders are created based on a template specified within the configuration of the SiftingAppender itself (enclosed within the <sift> element, see example below). SiftingAppender is responsible for managing the lifecycle of child appenders. For example, SiftingAppender will automatically close and remove any stale appender. A nested appender is considered stale when nothing accesses it beyond the duration specified by the timeout parameter.

When handling a logging event, SiftingAppender will select a child appender to delegate to. The selection criteria are computed at runtime by a discriminator. The user can specify the selection criteria with the help of a Discriminator. Let us now study an example.

Example

The SiftExample application logs a message stating that the application has started. It then sets the MDC key "userid" to "Alice" and logs a message. Here is the salient code:

logger.debug("Application started"); MDC.put("userid", "Alice"); logger.debug("Alice says hello");

The template for the configuration file illustrates the use of SiftingAppender.

Example: SiftingAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​sift/byUserid.xml)

<configuration>

  <appender name="SIFT" class="ch.qos.logback.classic.sift.SiftingAppender">
    <!-- in the absence of the class attribute, it is assumed that the
         desired discriminator type is
         ch.qos.logback.classic.sift.MDCBasedDiscriminator -->
    <discriminator>
      <key>userid</key>
      <defaultValue>unknown</defaultValue>
    </discriminator>
    <sift>
      <appender name="FILE-${userid}" class="ch.qos.logback.core.FileAppender">
        <file>${userid}.log</file>
        <append>false</append>
        <layout class="ch.qos.logback.classic.PatternLayout">
          <pattern>%d [%thread] %level %mdc %logger{35} -%kvp -%msg%n</pattern>
        </layout>
      </appender>
    </sift>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="SIFT" />
  </root>
</configuration>

In the absence of a class attribute, it is assumed that the discriminator type is MDCBasedDiscriminator. The discriminating value is the MDC value associated with the key given by the key property. However, if that MDC value is null, then defaultValue is used as the discriminating value.

The SiftingAppender is unique in its capacity to reference and configure child appenders. In the above example, SiftingAppender will create multiple FileAppender instances, each FileAppender instance identified by the value associated with the "userid" MDC key. Whenever the "userid" MDC key is assigned a new value, a new FileAppender instance will be built from scratch. The SiftingAppender keeps track of the appenders it creates. Appenders unused for 30 minutes will be automatically closed and discarded.

Variable export It is not enough to have different appender instances; each instance must output to a distinct target resource. To allow such differentiation, within the appender template, the key passed to the discriminator, "userid" in the above example, is exported and becomes a variable. Consequently, this variable can be used to differentiate the actual resource used by a given child appender.

Running the SiftExample application with the "byUserid.xml" configuration file shown above, will result in two distinct log files, "unknown.log" and "Alice.log".

local-scoped variables As of version 1.0.12, properties defined in local scope within the configuration file will be available to nested appenders. Moreover, you can define variables or dynamically compute variables from within the the <sift> element. Combining a variable from parts defined outside and within the <sift> element is also supported.

Getting the timeout right

For certain types of applications, it may be difficult to get the timeout parameter right. If the timeout is too small, a nested appender might be removed just to be created anew a few seconds later. This phenomenon is called trashing. If the timeout is too long and appenders are created in quick succession, you might run out of resources. Similarly, setting maxAppenderCount too low might cause trashing as well.

In many case, it may be easier to pinpoint a location in your code after which a nested appender is no longer needed. If such a location exists, even approximately, log from that location using the FINALIZE_SESSION marker. Whenever SiftingAppender sees a logging event marked as FINALIZE_SESSION it will end-of-life the associated nested appender. Upon reaching its end-of-life, a nested appender will linger for a few seconds to process any late coming events (if any) and then will be closed.

import org.slf4j.Logger;
import static ch.qos.logback.classic.​ClassicConstants.​FINALIZE_SESSION_MARKER;

  void job(String jobId) {
   
    MDC.put("jobId", jobId);
    logger.info("Starting job.");

    ... do whatever the job needs to do
    
    // will cause the nested appender reach end-of-life. It will
    // linger for a few seconds.
    logger.info(FINALIZE_SESSION_MARKER, "About to end the job");

    try {
      .. perform clean up
    } catch(Exception e);  
      // This log statement will be handled by the lingering appender. 
      // No new appender will be created.
      logger.error("unexpected error while cleaning up", e);
    }
  }

AsyncAppender

AsyncAppender logs ILoggingEvents asynchronously. It acts solely as an event dispatcher and must therefore reference another appender in order to do anything useful.

Lossy by default if 80% full AsyncAppender buffers events in a BlockingQueue. A worker thread created by AsyncAppender takes events from the head of the queue, and dispatches them to the single appender attached to AsyncAppender. Note that by default, AsyncAppender will drop events of level TRACE, DEBUG and INFO if its queue is 80% full. This strategy has an amazingly favorable effect on performance at the cost of event loss.

Application stop/redeploy Upon application shutdown or redeploy, AsyncAppender must be stopped in order to stop and reclaim the worker thread and to flush the logging events from the queue. This can be achieved by stopping the LoggerContext which will close all appenders, including any AsyncAppender instances. AsyncAppender will wait for the worker thread to flush up to the timeout specified in maxFlushTime. If you find that queued events are being discarded during close of the LoggerContext, you may need to increase the time-out. Specifying a value of 0 for maxFlushTime will force the AsyncAppender to wait for all queued events to be flushed before returning from the stop method.

Post shutdown cleanup Depending on the mode of JVM shutdown, the worker thread processing the queued events can be interrupted causing events to be stranded in the queue. This generally occurs when the LoggerContext is not stopped cleanly or when the JVM terminates outside of the typical control flow. In order to avoid interrupting the worker thread under these conditions, a shutdown hook can be inserted to the JVM runtime that stops the LoggerContext properly after JVM shutdown has been initiated. A shutdown hook may also be the preferred method for cleanly shutting down Logback when other shutdown hooks attempt to log events.

Here is the list of properties admitted by AsyncAppender:

By default, event queue is configured with a maximum capacity of 256 events. If the queue is filled up, then application threads are blocked from logging new events until the worker thread has had a chance to dispatch one or more events. When the queue is no longer at its maximum capacity, application threads are able to start logging events once again. Asynchronous logging therefore becomes pseudo-synchronous when the appender is operating at or near the capacity of its event buffer. This is not necessarily a bad thing. The appender is designed to allow the application to keep on running, albeit taking slightly more time to log events until the pressure on the appenders buffer eases.

Optimally tuning the size of the appenders event queue for maximum application throughput depends upon several factors. Any or all of the following factors are likely to cause pseudo-synchronous behavior to be exhibited:

• Large numbers of application threads
• Large numbers of logging events per application call
• Large amounts of data per logging event
• High latency of child appenders

To keep things moving, increasing the size of the queue will generally help, at the expense of heap available to the application.

Lossy behavior In light of the discussion above and in order to reduce blocking, by default, when less than 20% of the queue capacity remains, AsyncAppender will drop events of level TRACE, DEBUG and INFO keeping only events of level WARN and ERROR. This strategy ensures non-blocking handling of logging events (hence excellent performance) at the cost loosing events of level TRACE, DEBUG and INFO when the queue has less than 20% capacity. Event loss can be prevented by setting the discardingThreshold property to 0 (zero).

Example: AsyncAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​conc/logback-async.​xml)

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>myapp.log</file>
    <encoder>
      <pattern>%logger{35} -%kvp -%msg%n</pattern>
    </encoder>
  </appender>

  <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
    <appender-ref ref="FILE" />
  </appender>

  <root level="DEBUG">
    <appender-ref ref="ASYNC" />
  </root>
    </configuration>

Writing your own Appender

You can easily write your appender by subclassing AppenderBase. It handles support for filters, status messages and other functionality shared by most appenders. The derived class only needs to implement one method, namely append(Object eventObject).

The CountingConsoleAppender, which we list next, appends a limited number of incoming events on the console. It shuts down after the limit is reached. It uses a PatternLayoutEncoder to format the events and accepts a parameter named limit. Therefore, a few more methods beyond append(Object eventObject) are needed. As shown below, these parameters are handles auto-magically by logback's various configuration mechanisms.

package chapters.appenders;

import java.io.IOException;

import ch.qos.logback.classic.encoder.PatternLayoutEncoder;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.AppenderBase;


public class CountingConsoleAppender extends AppenderBase<ILoggingEvent> {
  static int DEFAULT_LIMIT = 10;
  int counter = 0;
  int limit = DEFAULT_LIMIT;
  
  PatternLayoutEncoder encoder;
  
  public void setLimit(int limit) {
    this.limit = limit;
  }

  public int getLimit() {
    return limit;
  }
  
  @Override
  public void start() {
    if (this.encoder == null) {
      addError("No encoder set for the appender named ["+ name +"].");
      return;
    }
    
    try {
      encoder.init(System.out);
    } catch (IOException e) {
    }
    super.start();
  }

  public void append(ILoggingEvent event) {
    if (counter >= limit) {
      return;
    }
    // output the events as formatted by our layout
    try {
      this.encoder.doEncode(event);
    } catch (IOException e) {
    }

    // prepare for next event
    counter++;
  }

  public PatternLayoutEncoder getEncoder() {
    return encoder;
  }

  public void setEncoder(PatternLayoutEncoder encoder) {
    this.encoder = encoder;
  }
}

The start() method checks for the presence of a PatternLayoutEncoder. In case the encoder is not set, the appender fails to start and emits an error message.

This custom appender illustrates two points:

• All properties that follow the setter/getter JavaBeans conventions are handled transparently by logback configurators. The start() method, which is called automatically during logback configuration, has the responsibility of verifying that the various properties of the appender are set and are coherent.
• The AppenderBase.doAppend() method invokes the append() method of its derived classes. Actual output operations occur in the append() method. In particular, it is in this method that appenders format events by invoking their layouts.

The CountingConsoleAppender can be configured like any other appender. See sample configuration file logback-examples/​src/main/resources/​chapters/appenders/​countingConsole.​xml for an example.

Logback Access

Most of the appenders found in logback-classic have their equivalent in logback-access. These work essentially in the same way as their logback-classic counterparts. In the next section, we will cover their use.

SocketAppender and SSLSocketAppender

The SocketAppender is designed to log to a remote entity by transmitting serialized AccessEvent objects over the wire. Remote logging is non-intrusive as far as the access event is concerned. On the receiving end after deserialization, the event can be logged as if it were generated locally.

The SSLSocketAppender extends the basic SocketAppender allowing logging to a remote entity over the Secure Sockets Layer (SSL).

The properties of access' SocketAppender are the same as those available for classic's SocketAppender.

ServerSocketAppender and SSLServerSocketAppender

Like SocketAppender, the ServerSocketAppender is designed to log to a remote entity by transmitting serialized AccessEvent objects over the wire. However, when using ServerSocketAppender the appender acts as a server, passively listening on a TCP socket awaiting inbound connections from interested clients. Logging events delivered to the appender are distributed to all connected clients.

The SSLSocketAppender extends the basic ServerSocketAppender allowing logging to a remote entity over the Secure Sockets Layer (SSL).

The properties of access' ServerSocketAppender are the same as those available for classic's ServerSocketAppender.

SMTPAppender

Access' SMTPAppender works in the same way as its Classic counterpart. However, the evaluator option is rather different. By default, a URLEvaluator object is used by SMTPAppender. This evaluator contains a list of URLs that are checked against the current request's URL. When one of the pages given to the URLEvaluator is requested, SMTPAppender sends an email.

Here is a sample configuration of a SMTPAppender in the access environment.

Example: SMTPAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​conf/access/logback-smtp.​xml)

<appender name="SMTP"
  class="ch.qos.logback.access.net.SMTPAppender">
  <layout class="ch.qos.logback.access.html.HTMLLayout">
    <pattern>%h%l%u%t%r%s%b</pattern>
  </layout>
    
  <Evaluator class="ch.qos.logback.access.net.URLEvaluator">
    <URL>url1.jsp</URL>
    <URL>directory/url2.html</URL>
  </Evaluator>
  <from>[email protected]</from>
  <smtpHost>mail.domain.com</smtpHost>
  <to>[email protected]</to>
</appender>

This way of triggering the email lets users select pages that are important steps in a specific process, for example. When such a page is accessed, the email is sent with the pages that were accessed previously, and any information the user wants to be included in the email.

DBAppender

DBAppender is used to insert the access events into a database.

As of logback version 1.2.8 DBAppender no longer ships with logback-access. However, DBAppender for logback-access is available under the following Maven coordinates:

ch.qos.logback.db:logback-access-db:1.​2.11.1

Two tables are used by DBAppender: access_event and access_event_header. They both must exist before DBAppender can be used. Logback ships with SQL scripts that will create the tables. They can be found in the logback-access/src/​main/java/ch/qos/​logback/access/​db/script directory. There is a specific script for each of the most popular database systems. If the script for your particular type of database system is missing, it should be quite easy to write one, taking as example one of the existing scripts. You are encouraged to contribute such missing scripts back to the project.

The access_event table's fields are described below:

The access_event_header table contains the header of each request. The information is organised as shown below:

All properties of classic's DBAppender are available in access's DBAppender. The latter offers one more option, described below.

Here is a sample configuration that uses DBAppender.

Example: DBAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​conf/access/logback-DB.xml)

<configuration>

  <appender name="DB" class="ch.qos.logback.access.db.DBAppender">
    <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource">
      <driverClass>com.mysql.jdbc.Driver</driverClass>
      <url>jdbc:mysql://localhost:3306/logbackdb</url>
      <user>logback</user>
      <password>logback</password>
    </connectionSource>
    <insertHeaders>true</insertHeaders>
  </appender>

  <appender-ref ref="DB" />
</configuration>

SiftingAppender

The SiftingAppender in logback-access is quite similar to its logback-classic counterpart. The main difference is that in logback-access the default discriminator, namely AccessEventDiscriminator, is not MDC based. As its name suggests, AccessEventDiscriminator, uses a designated field in AccessEvent as the basis for selecting a nested appender. If the value of the designated field is null, then the value specified in the defaultValue property is used.

The designated AccessEvent field can be one of COOKIE, REQUEST_ATTRIBUTE, SESSION_ATTRIBUTE, REMOTE_ADDRESS, LOCAL_PORT, REQUEST_URI. Note that the first three fields require that the AdditionalKey property also be specified.

Below is an example configuration file.

Example: SiftingAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​conf/sift/access-siftingFile.​xml)

<configuration>
  <appender name="SIFTING" class="ch.qos.logback.access.sift.SiftingAppender">
    <Discriminator class="ch.qos.logback.access.sift.AccessEventDiscriminator">
      <Key>id</Key>
      <FieldName>SESSION_ATTRIBUTE</FieldName>
      <AdditionalKey>username</AdditionalKey>
      <defaultValue>NA</defaultValue>
    </Discriminator>
    <sift>
       <appender name="ch.qos.logback:logback-site:jar:1.5.12" class="ch.qos.logback.core.FileAppender">
        <file>byUser/ch.qos.logback:logback-site:jar:1.5.12.log</file>
        <layout class="ch.qos.logback.access.PatternLayout">
          <pattern>%h %l %u %t \"%r\" %s %b</pattern>
        </layout>
      </appender>
    </sift>
  </appender>
  <appender-ref ref="SIFTING" />
</configuration>

In the above configuration file, a SiftingAppender nests FileAppender instances. The key "id" is designated as a variable which will be available to the nested FileAppender instances. The default discriminator, namely AccessEventDiscriminator, will search for a "username" session attribute in each AccessEvent. If no such attribute is available, then the default value "NA" will be used. Thus, assuming the session attribute named "username" contains the username of each logged on user, there will be a log file under the byUser/ folder (of the current folder) named after each user containing the access logs for that user.