Manual · Appenders · Appenders: logback-access

Appenders: logback-access

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.

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.common.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.common.net.URLEvaluator">
    <URL>url1.jsp</URL>
    <URL>directory/url2.html</URL>
  </Evaluator>
  <from>sender_email@host.com</from>
  <smtpHost>mail.domain.com</smtpHost>
  <to>recipient_email@host.com</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:

Field	Type	Description
timestamp	big int	The timestamp that was valid at the access event's creation.
requestURI	varchar	The URI that was requested.
requestURL	varchar	The URL that was requested. This is a string composed of the request method, the request URI and the request protocol.
remoteHost	varchar	The name of the remote host.
remoteUser	varchar	The name of the remote user.
remoteAddr	varchar	The remote IP address.
protocol	varchar	The request protocol, like HTTP or HTTPS.
method	varchar	The request method, usually GET or POST.
serverName	varchar	The name of the server that issued the request.
event_id	int	The database id of the access event.

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

Field	Type	Description
event_id	int	The database id of the corresponding access event.
header_key	varchar	The header name, for example User-Agent.
header_value	varchar	The header value, for example Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.1) Gecko/20061010 Firefox/2.0

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

Property Name	Type	Description
insertHeaders	boolean	Tells the DBAppender to populate the database with the header information of all incoming requests.

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="${id}" class="ch.qos.logback.core.FileAppender">
        <file>byUser/${id}.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.