com.ibm.websphere.als
Class AnalysisLogger

java.lang.Object
  |
  +--com.ibm.websphere.als.AnalysisLogger

public class AnalysisLogger

extends java.lang.Object

This is the entry into the logging facility. Any application needs to log data must create an instance of this class using the appropriate constructor. Since this class listens on the ServletContext events to determine when to log data to the persistent storage, to use it in an EJB, pass null for the ServletContext so that it doesn't listen for the ServletContext events. And in this case, the application is responsible for calling flush method at the appropriate interval. Method getLogSize may be used as a determination criteria.

There are 3 persistent storage implementations: Database, File, and HTTP. Use appropriate constructor to enable each one. The Database persistence is implemented by DatabaseLogger class. The application is responsible for setting up the database and the table as defined by the DatabaseLogger class. This class works with any database supports JDBC. The File persistence is implemented by FileLogger class. FileLogger is not clusterable; that is, it must be defined on all machines participating in a cluster. The HTTP persistence is implemented by HttpLogger class. It supports both HTTP and HTTPS transport. However, HTTPS is not recommended if the traffic volume is high.

Application may define custom-logger by implementing the interface Logger. To enable debug trace, set com.ibm.websphere.als.*=all=enabled.

 Sample usage for IBM DB2:

 DatabaseLogger dblogger = new DatabaseLogger(ds, "CURRENT TIMESTAMP",
                                              "WAS.ALS", "db2admin", "db2admin");
 AnalysisLogger logger = new AnalysisLogger(context, dblogger);
 ...
 logger.log(request, "sample=testing;");
 

See Also:

Logger, DatabaseLogger, FileLogger, HttpLogger

Field Summary

protected static com.ibm.ejs.ras.TraceComponent

myTracer

Constructor Summary

AnalysisLogger(javax.servlet.ServletContext sc, Logger l)
Constructs an AnalysisLogger object with the default cache size of 50 entries.

AnalysisLogger(javax.servlet.ServletContext sc, Logger l, int maxBufferSize)
Constructs an AnalysisLogger object.

Method Summary

static void	debug(java.lang.Exception e)
void	flush() Flushes the data in the cache.
java.lang.String	getAppID() Returns the current application ID.
boolean	getAutoSession() Returns the auto-create session flag.
boolean	getCookieLogging() Returns the COOKIE logging flag.
boolean	getHttpLogging() Returns the HTTP logging flag.
Logger	getLogger() Returns the current Logger object.
int	getLogSize() Returns the number of log entries currently in the buffer awaiting to be written to the permanent storage.
boolean	isEnabled() Returns the logging enabled flag.
void	log(javax.servlet.http.HttpServletRequest hsr, java.lang.String data) Logs the specified data.
void	log(javax.servlet.http.HttpServletRequest hsr, java.lang.String key, java.lang.String value) Logs the specified data.
void	setAppID(java.lang.String appID) Sets the application ID.
void	setAutoSession(boolean value) Sets the auto-create session flag to value.
void	setCookieLogging(boolean value) Sets the COOKIE logging flag to value.
void	setEnabled(boolean value) Sets the logging enabled flag to value.
void	setHttpLogging(boolean value) Sets the HTTP logging flag to value.
void	terminate() Stops logging and releases all associated resources.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

myTracer

protected static com.ibm.ejs.ras.TraceComponent myTracer

Constructor Detail

AnalysisLogger

public AnalysisLogger(javax.servlet.ServletContext sc,
                      Logger l)

Constructs an AnalysisLogger object with the default cache size of 50 entries.

Parameters:

sc - a ServletContext of the webapp requesting the logging. If this param is null, flusing the cache is done as part of log() invocation. This behavior is necessary for EJB logging.

l - a Logger responsible for writing data to persistent storage

See Also:

Logger

AnalysisLogger

public AnalysisLogger(javax.servlet.ServletContext sc,
                      Logger l,
                      int maxBufferSize)

Constructs an AnalysisLogger object.

Parameters:

sc - a ServletContext of the webapp requesting the logging. If this param is null, flusing the cache is done as part of log() invocation. This behavior is necessary for EJB logging.

l - a Logger responsible for writing data to persistent storage

maxBufferSize - a maximum number of entries cached in the buffer before calling flush()

See Also:

Logger

Method Detail

log

public void log(javax.servlet.http.HttpServletRequest hsr,
                java.lang.String data)
         throws java.lang.Exception

Logs the specified data. The data is kept in the buffer and written to permanent storage based on 2 factors--the number of the distinct entries in the buffer reaches maxBufferSize specified in the constructor, or the time elapse since last flush has been longer than a minute. The format of the data is key=value;. Note that the semicolon is appended to the value automatically.

Parameters:

hsr - - the HttpServletRequest of the request. If this param is null, a unique sequence number is generated for the REQID, and the session ID is zero

data - - a well-formated and semicolon-terminated string

Throws:

java.lang.Exception - - thrown when unable to write data

log

public void log(javax.servlet.http.HttpServletRequest hsr,
                java.lang.String key,
                java.lang.String value)
         throws java.lang.Exception

Logs the specified data. The data is kept in the buffer and written to permanent storage based on 2 factors--the number of the distinct entries in the buffer reaches maxBufferSize specified in the constructor, or the time elapse since last flush has been longer than a minute. The format of the data is key=value;. Note that the semicolon is appended to the value automatically.

Parameters:

hsr - - the HttpServletRequest of the request. If this param is null, a unique sequence number is generated for the REQID, and the session ID is zero

key - - the key of the data

value - - the value of the data

Throws:

java.lang.Exception - - thrown when unable to write data

flush

public void flush()
           throws java.lang.Exception

Flushes the data in the cache. Webapp doesn't have to call this method since the cache is flushed automatically based on the time elapse since last log and the size of the data in the cache during processing of ApplicationListener and ServletInvocationListener event. In the case of no valid ServletContext object (non-webapp), the application might wish to invoke this method directly to store the content of the cache.

Throws:

java.lang.Exception - - thrown when unable to write data

See Also:

getLogSize()

setEnabled

public void setEnabled(boolean value)

Sets the logging enabled flag to value. This is a convenient way for the application to turn logging on or off. The default value is true.

Parameters:

value - - value to set enable flag to

isEnabled

public boolean isEnabled()

Returns the logging enabled flag. This is a convenient way for the application to check for logging status.

setHttpLogging

public void setHttpLogging(boolean value)

Sets the HTTP logging flag to value. Application should turn off HTTP logging if it is not needed. If this flag is off, the HttpData field that is logged will be null. The default value is true.

Parameters:

value - - value to set HTTP logging flag to

getHttpLogging

public boolean getHttpLogging()

Returns the HTTP logging flag.

setCookieLogging

public void setCookieLogging(boolean value)

Sets the COOKIE logging flag to value. Application should turn off COOKIE logging if it is not needed. If this flag is false, the COOKIE field that is logged will be null. The default value is true.

Parameters:

value - - value to set COOKIE logging flag to

getCookieLogging

public boolean getCookieLogging()

Returns the COOKIE logging flag.

setAutoSession

public void setAutoSession(boolean value)

Sets the auto-create session flag to value. If this flag is true and if the session object doesn't exist for a request, a session object will be automatically created before processing logging for that request. The default value is true.

If the application doesn't track session and auto-create is true, the log method should be called at least once before any output is written to the response object

Parameters:

value - - value to set auto-create session flag to

getAutoSession

public boolean getAutoSession()

Returns the auto-create session flag.

getLogger

public Logger getLogger()

Returns the current Logger object.

setAppID

public void setAppID(java.lang.String appID)

Sets the application ID. The application ID is logged with the record.

Parameters:

appID - - a String representing the application ID, limited to 128 characters

getAppID

public java.lang.String getAppID()

Returns the current application ID.

getLogSize

public int getLogSize()

Returns the number of log entries currently in the buffer awaiting to be written to the permanent storage. This value may be used as a criteria to call flush() method.

terminate

public void terminate()

Stops logging and releases all associated resources. None webapp should call this method prior to terminating.

debug

public static void debug(java.lang.Exception e)