Log4j 2.0alpha-1

org.apache.log4j.db
Class CustomSQLDBReceiver

java.lang.Object
  extended by org.apache.log4j.spi.ComponentBase
      extended by org.apache.log4j.plugins.PluginSkeleton
          extended by org.apache.log4j.plugins.Receiver
              extended by org.apache.log4j.db.CustomSQLDBReceiver
All Implemented Interfaces:
org.apache.log4j.plugins.Pauseable, org.apache.log4j.plugins.Plugin, org.apache.log4j.spi.Component, org.apache.log4j.spi.OptionHandler, org.apache.log4j.spi.Thresholdable

public class CustomSQLDBReceiver
extends Receiver
implements org.apache.log4j.plugins.Pauseable

Converts log data stored in a database into LoggingEvents.

NOTE: This receiver cannot yet be created through Chainsaw's receiver panel. It must be created through an XML configuration file.

This receiver supports database configuration via ConnectionSource, in the org.apache.log4j.db package: DriverManagerConnectionSource, DataSourceConnectionSource, JNDIConnectionSource

This database receiver differs from DBReceiver in that this receiver relies on custom SQL to retrieve logging event data, where DBReceiver requires the use of a log4j-defined schema.

A 'refreshMillis' int parameter controls SQL execution. If 'refreshMillis' is zero (the default), the receiver will run only one time. If it is set to any other numeric value, the SQL will be executed on a recurring basis every 'refreshMillis' milliseconds.

The receiver closes the connection and acquires a new connection on each execution of the SQL (use pooled connections if possible).

If the SQL will be executing on a recurring basis, specify the IDField param - the column name holding the unique identifier (int) representing the logging event.

As events are retrieved, the column represented by IDField is examined and the largest value is held and used by the next execution of the SQL statement to avoid retrieving previously processed events.

As an example, the IDField references a 'COUNTER' (int, auto-increment, unique) column. The first execution of the SQL statement returns 500 rows, with a final value in the COUNTER field of 500.

The SQL statement is manipulated prior to the next execution, adding ' WHERE COUNTER > 500' to the statement to avoid retrieval of previously processed events.

The select statement must provide ALL fields which define a LoggingEvent.

The SQL statement MUST include the columns: LOGGER, TIMESTAMP, LEVEL, THREAD, MESSAGE, NDC, MDC, CLASS, METHOD, FILE, LINE, PROPERTIES, EXCEPTION

Use ' AS ' in the SQL statement to alias the SQL's column names to match your database schema. (see example below).

Include all fields in the SQL statement, even if you don't have data for the field (specify an empty string as the value for columns which you don't have data).

The TIMESTAMP column must be a datetime.

Both a PROPERTIES column and an MDC column are supported. These fields represent Maps on the logging event, but require the use of string concatenation database functions to hold the (possibly multiple) name/value pairs in the column.

For example, to include both 'userid' and 'lastname' properties in the logging event (from either the PROPERTIES or MDC columns), the name/value pairs must be concatenated together by your database.

The resulting PROPERTIES or MDC column must have data in this format: {{name, value, name2, value2}}

The resulting PROPERTIES column would contain this text: {{userid, someone, lastname, mylastname}}

Here is an example of concatenating a PROPERTIES or MDC column using MySQL's concat function, where the 'application' and 'hostname' parameters were fixed text, but the 'log4jid' key's value is the value of the COUNTER column:

concat("{{application,databaselogs,hostname,mymachine,log4jid,", COUNTER, "}}") as PROPERTIES

log4jid is a special property that is used by Chainsaw to represent an 'ID' field. Specify this property to ensure you can map events in Chainsaw to events in the database if you need to go back and view events at a later time or save the events to XML for later analysis.

Here is a complete MySQL SQL statement which can be used to provide events to Chainsaw:

select logger as LOGGER, timestamp as TIMESTAMP, level as LEVEL, thread as THREAD, message as MESSAGE, ndc as NDC, mdc as MDC, class as CLASS, method as METHOD, file as FILE, line as LINE, concat("{{application,databaselogs,hostname,mymachine, log4jid,", COUNTER,"}}") as PROPERTIES, "" as EXCEPTION from logtable

Author:
Scott Deboy


Field Summary
protected  java.sql.Connection connection
           
protected  java.lang.String idField
           
static java.lang.String LOG4J_ID_KEY
           
protected  java.lang.String sqlStatement
           
 
Fields inherited from class org.apache.log4j.plugins.Receiver
thresholdLevel
 
Fields inherited from class org.apache.log4j.plugins.PluginSkeleton
active, name
 
Fields inherited from class org.apache.log4j.spi.ComponentBase
repository
 
Constructor Summary
CustomSQLDBReceiver()
           
 
Method Summary
 void activateOptions()
           
 void close()
           
 void finalize()
           
 org.apache.log4j.db.ConnectionSource getConnectionSource()
           
 java.lang.String getIDField()
           
 int getRefreshMillis()
           
 java.lang.String getSql()
           
 boolean isPaused()
           
 void setConnectionSource(org.apache.log4j.db.ConnectionSource connectionSource)
           
 void setIDField(java.lang.String id)
           
 void setPaused(boolean p)
           
 void setRefreshMillis(int refreshMillis)
           
 void setSql(java.lang.String s)
           
 void shutdown()
           
 
Methods inherited from class org.apache.log4j.plugins.Receiver
doPost, getThreshold, isAsSevereAsThreshold, setThreshold
 
Methods inherited from class org.apache.log4j.plugins.PluginSkeleton
addPropertyChangeListener, addPropertyChangeListener, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getLoggerRepository, getName, isActive, isEquivalent, removePropertyChangeListener, removePropertyChangeListener, setLoggerRepository, setName
 
Methods inherited from class org.apache.log4j.spi.ComponentBase
getLogger, getNonFloodingLogger, resetErrorCount
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

connection

protected volatile java.sql.Connection connection

sqlStatement

protected java.lang.String sqlStatement

idField

protected java.lang.String idField

LOG4J_ID_KEY

public static final java.lang.String LOG4J_ID_KEY
See Also:
Constant Field Values
Constructor Detail

CustomSQLDBReceiver

public CustomSQLDBReceiver()
Method Detail

activateOptions

public void activateOptions()
Specified by:
activateOptions in interface org.apache.log4j.spi.OptionHandler

setRefreshMillis

public void setRefreshMillis(int refreshMillis)

getRefreshMillis

public int getRefreshMillis()

getConnectionSource

public org.apache.log4j.db.ConnectionSource getConnectionSource()
Returns:
Returns the connectionSource.

setConnectionSource

public void setConnectionSource(org.apache.log4j.db.ConnectionSource connectionSource)
Parameters:
connectionSource - The connectionSource to set.

close

public void close()

finalize

public void finalize()
Overrides:
finalize in class java.lang.Object

shutdown

public void shutdown()
Specified by:
shutdown in interface org.apache.log4j.plugins.Plugin

setSql

public void setSql(java.lang.String s)

getSql

public java.lang.String getSql()

setIDField

public void setIDField(java.lang.String id)

getIDField

public java.lang.String getIDField()

setPaused

public void setPaused(boolean p)
Specified by:
setPaused in interface org.apache.log4j.plugins.Pauseable

isPaused

public boolean isPaused()
Specified by:
isPaused in interface org.apache.log4j.plugins.Pauseable

Log4j 2.0alpha-1

Copyright 2000-2003 Apache Software Foundation.