Right Java tools for J2EE, Web Service, Grid and more
|Home | Products | Documents | Downloads | Purchase | Support | Company | Partners | Contact |
SuperLogging

Java EE (Java Enterprise Edition) is the new name for the Java platform. But J2EE (Java 2 Enterprise Edition) is still widely used. In this document J2EE and Java EE are interchangeable.

Table of Contents

Overview

SuperLogging is a full featured J2EE logging system. It is for recording events and messages.  The main features are:

The log records in the log database is the information resources for other facilities.

The architecture

The Structure

SuperLogging consists of:
  1. Server side components: SuperLoggingLibrary (server side library), control component (SuperLoggingEJB/SuperLoggingServlet),  JDBC Driver and log database.
  2. Client side component:  Logging Manager. It is a Swing GUI tool as the remote controller.

Control component and the server side library are J2EE specification compliant. They are J2EE vendor neutral. They run on the server side. Control component is for management only. Log messages are directly recorded into the log database.

The Logging Manager is a toolkit to manage and monitor the whole facilities dynamically. It is part of Super (the client). It is written entirely in the Java programming language with Swing GUI. It is operating system neutral and J2EE vendor neutral. 

This architecture make SuperLogging simple, fast, powerful and easy to use. It is open and flexible as well.

The control flow

On the server side: Applications (EJB, JSP or Java helper classes) use log methods to log messages and events. Log methods are defined in com.acelet.logging.Logging. SuperLogging filters out unwanted calls, then records log messages. If anything goes wrong, SuperLogging will send alert emails.

On the client side: Users use the Logging Manager to dynamically configure settings of server side SuperLogging. When settings changes, the caller's eligibility may change on the server side. Users can do source code level tracing as well. The Logging Manager does its job through control component. The Logging Manager supports distributed computing environment. Configuration changes take effect on every instance of SuperLogging of the server side on all the instances of servers.

Clear separation between request and management

There are two pieces of logic in logging: logging request and logging management. A logging request is materialized in applications by calling log methods. Log message text, log level are specified in the method call. The logging request is checked by SuperLogging using management logic. If a request is eligible, the log message will be recorded.

All methods for logging requests are in com.acelet.logging.Logging. All methods for logging management are in com.acelet.logging.SuperLogging, which is part of control component. Because of this separation, there will be little chance to mix these two different logics unintentionally. 

Usually, all logging requests are in user's application. All management functionality is inside SuperLogging and controlled by GUI tool at run time. Of course, you can manage SuperLogging programmatically inside your application by calling SuperLogging EJB/SuperLoggingSevlet. All management methods of SuperLogging are distributing-computing-safe. Every management method keeps all instances of SuperLogging in sync. 
 

SuperLoggingEJB/SuperLoggingServlet

SuperLoggingEJB/SuperLoggingServlet is the bridge between Super GUI client (controller) and SuperLoggingLibrary for management. 

If there is a firewall between your Super GUI client and your application server, you can use VNC, tunneling or Web Service. See Get around the firewall in SuperArch for more information.

You need to add security constrains to the Deployment Descriptor of SuperLoggingEJB/SuperLoggingServlet according to your needs. 

SuperLogging zone

The effective zone of SuperLogging is wider than the cluster. SuperLogging is effective on all programs which uses the same log database. 

Prerequisite

See Prerequisite in Installation for general prerequisite.

Fail-stop on failure

In no circumstances SuperLogging will affect the execution of your applications (EJBs or JSPs). In the scenario of log database errors, SuperLogging will:

1. Send an alert message asking administrator's help.
2. Set an internal flag for ignoring all log method calls from that time on, so the log statement calls will not waste time to wait for accessing the log database.

When the log database is up and running again, logging can be resumed from the Logging Manager. See Reconnect broken log database for details.
 
Log methods of SuperLogging do not throw exceptions at run-time and will not cause your application to crash. Instead, it sends alert email to administrators. You can set the interval to avoid flooding of alert email as well. See Alert email for details.

Log methods

Applications (EJB, JSP or Java helper classes) use log methods to log events and messages. Log methods are defined in  com.acelet.logging.Logging  and  com.acelet.opensource.logging.Alog. These two classes have the same set of methods. You can use either or both. See Open source wrapper for explanation.

Log methods are: 

  public static void log(String msg, int level)
  public static void log(String msg, int level, String producer, String why)

It is very simple for users: no preparation, no initialization. The above methods detect caller (application class) information automatically. 

The following log methods are for backward compatibility:
  public static void log(String msg, int level, String fullClassName, String methodName, String baseFileName, int lineNumber)
  public static void error(String text, int level, String fullClassName, String methodName, String baseFileName, int lineNumber)

Usage

Call log method is very simple. There is no initialization, no preparation. Just call these static methods anywhere in your EJB, JSP and helper class. For example:

    Logging.log("number=" + number, Logging.FINE);

You only need to provide your business message and log level.


SuperLogging is thread safe: you can call it from different EJBs concurrently.

Log devices

The available log devices are:

The STDOUT and STDERR are your screen, they are defined by your operating system. DATABASE is a database for log messages and must be selected.

Note: STDOUT and STDERR are convenient for development. But, they may slow down your application.

Database as output device

The log messages on the DATABASE device are persistent.

The log database activity is not part of your application's transaction. The log information on the log database is never ROLLBACKed, just like the log information on the screen.

The log database connection must be a dedicated connection, and not a part of application server connection pool. SuperLogging manages its database transaction itself, this transaction is transparent to the user. The accesses to log database from SuperLogging are optimized in favor of speed.

The log database must run as a database server.  The log database server must be up and running when the J2EE application server is running.

The default log database is HypersonicSQL, which communicates with the server side library of the SuperLogging through a port (default is 23536).

The log database can be maintained from the Log Database Panel. HypersonicSQL is a standard SQL database. You can use any third party software to manage it as well.
 

Log level and log threshold

Log level is a level of request. Each log method call has a log level argument. The value is hard coded by application developers and can not be changed at run time.

Log threshold is an attribute of SuperLogging. It is dynamically configurable at run time.

When a log method is invoked, SuperLogging checks log level of the method call against the threshold. If the log level is equal or higher than SuperLogging's threshold, this method call is an eligible candidate for log message recording. SuperLogging also checks if the caller class (Java class) or file (JSP file) is registered or not. If it is registered, the log message will be recorded.

Note: both Quiet and Verbose modes ignore log level.

Example: Suppose you set a threshold on SuperLogging to be 500. The following call (with log level 300, which is less than 500) is not eligible:

    Alog.log("number=" + number, 300);

while the next call (with log level 900, which is higher than 500) is eligible:

    Alog.log("number=" + number, 900);

If you reconfigure the threshold to be 100, both the above calls will be eligible.

The data type of both log level and threshold are int. They can be any value of int. The following category is recommended by Java as a guideline:

SEVERE = 1000; //something will prevent normal program execution.
WARNING = 900; //something has potential problems.
INFO = 800; //for significant messages.
CONFIG = 700; //for config information in debugging.
FINE = 500; //for information such as recoverable failures.
FINER = 400; //for information about entering or returning a method, or throwing an exception.
FINEST = 300; //for detail tracing information.
The above attributes are defined in com.acelet.logging.Logging and com.acelet.opensource.logging.Alog. For example, you can code like:

    Alog.log("number=" + number, Alog.FINE);
or

    Alog.log("number=" + number, Logging.FINE);
 
Class and file registration

In Conditional mode, only the registered Java classes or JSP files will be eligible candidates for log message generation.

Any Java class or JSP file can be registered or un-registered dynamically.

Both Quiet and Verbose modes ignore this registration.

Note: The registration registers Java classes using their full names (package name plus base name). But for JSP, the Java class is generated by the server. The naming conventions are different from server to server. For example, Weblogic will generate jspLogging.jsp as 

  full class name: jsp_servlet.__jsplogging
  file name: __jsplogging.java

There is no user defined package name for JSP, so avoid using the same file name under different directories for JSP files.

Attribute

Attribute controls the characteristics of SuperLogging. The attributes are:

Attribute changing take effect in different ways for different scope:

Scope

This is an advanced topic. The default value (Dynamic) should be good if your system is not too busy.

Scope is the space or area in which the Attribute and class registration settings are applicable.  Because J2EE is in a distributed environment, the scope can be within one physical machine or span to many physical machines.

Scope can be one of the following values:

Dynamic (default): All instances of  the server side libraries get the configurable settings from the central log database dynamically. All instances of these libraries work with the same attribute and use the same class registration.  Because the server side libraries read the settings every time it is invoked, there is some overhead incurred, but the performance penalty may or may not be severe for you.

Configuration settings are synchronized among all programs which use the same log database, including all servers in clusters and independent servers, within one domain, or many domains, even for programs written in other languages.

Static: All instances of  the server side libraries get the configurable settings from the central log database at the beginning by downloading. The settings are kept in memory and never change. When a log method is invoked, SuperLogging checks settings in memory, so it is fast. Comparing to Dynamic, the flexibility is lost for gaining performance.

Configuration settings are synchronized among all programs which use the same log database, including all servers in clusters and independent servers, within one domain, or many domains, even for programs written in other languages. But, if you want to change Static to other scope, all above programs must be reachable by JMS messaging.

Smart: All instances of  the server side libraries get the configurable settings from the central log database at the beginning by downloading. The settings are kept in memory. When a log method is invoked, SuperLogging checks settings in memory, so it is fast, just like Static mode. When the setting of SuperLogging changes, all instances of the server side libraries will get a notification messaging and download new settings from the central log database to update their memory. Smart mode is both flexible and fast. 

Configuration settings are synchronized among all programs which use the same log database, including all servers in clusters and independent servers, within one domain, or many domains, even for programs written in other languages, as long as all above programs must be reachable by JMS messaging.

Singleton: It provides both flexibility and performance. But it is valid for one JVM only. The global-ness is lost. It can not be used in distributed computing environment, because the configuration is not synchronized among J2EE servers.
 
Change scope

This is an advanced topic. The default value (Dynamic) should be good if your system is not too busy.

The Scope Panel shows the current scope on the server at the time it is opened. When you change the scope, the following will happen:

1. Change from Dynamic to other scope takes effect immediately.

2. Change from Static, Smart or Singleton to a different scope is managed by JMS messaging. The messaging is sent immediately. 

3. Change from any scope to Singleton takes effect immediately. Do not make this change if there are multi-instances of the server side libraries running. Otherwise, only the server that talks to the Attribute Panel can be controlled. Others are out of control.

Note: You must Set JMS connection factory and topic. Otherwise the changes which require messaging will take effect on the next server restart. If there are multi-servers, all servers need restart. 
 
Set JMS connection factory and topic

If you want to change scope from Static, Smart or Singleton to others, you must set a JMS connection factory and a topic. 

JMS connection factory: The JNDI name of it must be SuperLoggingTopicFactory. It must be visible for all instances of J2EE application servers.

JMS topic: The JNDI name of it must be SuperLoggingChange. It must be visible for all instances of J2EE application servers.

J2EE/JMS specifications do not standardize the way to set these items. So the way to set is different from server to server. See Setup JMS connection factory and topic for logging scope change for detailed information.

Communication among instances of SuperLogging

If Global or Static scope is used, there is no direct communication among instances of SuperLogging. But, if Smart scope is used, there is communication among instances of SuperLogging.

The communication among instances of SuperLogging uses JMS. SuperLogging uses JMS to synchronize themselves. The communication takes some time, usually in milliseconds. This time delay is not avoidable, because each server uses its own JVM.

J2EE application servers use JMS as internal communication tool as well. For example, when you register an object to the JNDI context, the Weblogic administration server of the cluster communicates with member servers through JMS. There is a small delay among servers. It will not happen at the exactly same scientific moment. 

Reset Library

In a distributed computing environment, there are many instances of SuperLoggingLibrary. Each instance of them connects to the log database. These instances do not know each other. In the following scenarios you need to reset libraries:

SuperLogging provides the following reset options:

No matter which option you choose, the command reset takes action immediately on all instances of SuperLoggingLibrary by sending JMS messaging. Usually JMS messaging reaches it destination in milliseconds. When an instance gets an order to reset, it does it immediately.

Open source wrapper

An open source wrapper com.acelet.opensource.logging.Alog is provided for preventing vendor lock in. There is no business logic inside the wrapper. It just redirects the call. If another logging software is chosen, you do not need to modify your application source code . In that case,  the only modification needed is in this wrapper, which is just a few lines of code.

Both com.acelet.logging.Logging   and open source com.acelet.opensource.logging.Alog provide logging methods with the same method signatures. You can use either or both of them.

Programmatically configure

All attributes and settings of SuperLogging can be dynamically and programmatically configured as well. 

All these management methods are distributing-computing-safe. These methods are in SuperLoggingEJB/SuperLoggingServlet.
 
Tracing

Your EJBs, JSPs and helper classes log messages into log database through SuperLogging. The log database is the resource for source code level tracing. You can do source level tracing from the Tail Panel. Usually, the context on the Tail Panel moves quickly, tracing is better served with SuperTracer.

If you directly write log records in correct format into the log database outside of SuperLogging, your records will be valid candidates for source code level tracing as well, regardless of what language you use. Specifications are available.

SuperTracer is good for tracing the live log database, as well as retired (historical) log databases.

Tail

The Tail facility repeatedly show new log records on Tail Panel. Tail is similar with Unix command "tail".

The Tail Panel is the dynamic version of  Tracer Panel of SuperTracer, with syntax highlighting and source code level tracing.

Syntax highlighting

The Tail Panel displays log information with syntax highlighting shows different color for different column. It uses Syntax highlighting facility of SuperTracer and uses the same color settings. 

Filter

The Filter filters unwanted log messages using WHERE clause of SQL. To be user friendly, SuperLogging provides a GUI input panel for the time period part of the WHERE clause.

Columns of SuperLogging message table

SuperLogging stores log records stored in the log database. The columns of SuperLogging message table are: 

timemark BIGINT,
hostname VARCHAR(100),
threadName VARCHAR(100),
producer VARCHAR(100),
fullClassName VARCHAR(100), 
methodName VARCHAR(100), 
fileAndLine VARCHAR(100), 
why VARCHAR(100), 
msg VARCHAR(1024),

BIGINT here is equivalent to long in Java. The actual data type is database dependent.

This table is compatible with LimpidLog.

You can use any combination of these columns to construct WHERE clause for filtering.

Alert Email

When the system needs administrator's attention, alert email will be sent out to system administrators on duty. 

See Differences between Alert and Alarm for related information.

To avoid flooding of alert email, an alert interval is used to suppress alert email in that interval. When you get an alert email, that is the first alert email in that interval. There are possibly more. So you need to check your system thoroughly.

You can embed alert calls in your application as well.

Alert email parameters are stored in the log database. The default values are:

    adminEmailAddress = "";    // not valid, must set
  alertEmailAddress = "";      // not valid, must set
  alertInterval = 15 minutes
  mailHostName = "mailhost";   // may not be valid, must set

You must set these parameters with valid values before you can use the alert facilities. These parameters can be changed any time from the Alert Email Panel. All changes will not take effect until library reset or J2EE application server restart. Regardless of what the scope is, the latest alert email parameter values will be used when an alert email is sent out.

See Generic email aliases are recommended for related information.

Alarm Email

When your business has problems, you need to notify people who are in charge. Probably different people are responsible for different issues. So Alarm system has many entries, each entry is identified by a subject. Each entry has its own notification address (comma delimited email addresses) and alarm interval. Alarm will send notification to destination according to its subject. 

See Differences between Alert and Alarm for related information.

Alarm interval is used to suppress alarm email in that interval, to avoid email flooding.

When alarm is called, the system searches its subject,  finds corresponding email address and sends notification email. If the subject does not have a corresponding entry, the default entry will be used. The default entry is identified by subject "!default".

You can embed alarm calls in your application.

See Generic email aliases are recommended for related information.

Differences between Alert and Alarm

The main difference between Alert and Alarm is: Alarm is designed for business notification while Alert is designed for system notification. 

Alert notifies the system administrators on duty. There is only one destination which is comma separated email addresses. Alarm notifies the people who are in charge according to the subject of the alarm. So there are many destinations, each of them is a comma separated email addresses.

Email Facility

You can send email using a simple method call from com.acelet.Logging.sendMail( ) or com.acelet.opensource.logging.Alog.sendMail( ).

There are two methods with different parameter lists.

Note: Mail delivery failure notification may be immediate (i.e. an Exception) or delayed, depending on reasons and the actual underlying email system.
 
Generic email aliases are recommended

A very useful way of using email aliases is to set up a generic email address for positions and point them to the persons that is currently in that role. Generic ones can prevent a lot of of maintenance. For example, the alert email address can be alert@acelet.com forwarding to jane.doe@acelet.com If Jane is on vacation, you can easily to re-forward to john.doe@acelet.com, without changing alert email address.

Differences between attribute and parameter

Attribute controls the characteristics of SuperLogging. It needs to be dynamically re-configurable.

Parameters are data for setup SuperLogging. It does not need to be dynamically re-configurable. When parameters changes, you need to re-deploy SuperLoggingEJB/SuperLoggingServlet or your applications which use SuperLogging.

Parameters

Logging parameters are parameters for log database and parameters for JMS. They are different from attributes. See Differences between attribute and parameter for details.

Parameters are in a properties file, named logDatabaseParameters, on the directory of com/acelet/logging/ of SuperLoggingLibrary.  All your application which use SuperLogging need to access SuperLoggingLibrary. Logging parameters must be identical for SuperLogging and all applications which use them on all application servers, on all physical machines.

The default log database is HypersonicSQL. The default values of the log database parameters are hard coded in the library:

driverName = "org.hsql.jdbcDriver";  //HupersonicSQL
databaseUrl = "jdbc:HypersonicSQL:http://localhost:23536";
databaseUserName = "acelet";
databasePassword = "acelet";
queryTimeout=15

queryTimeout is the time out for each access to the log database. The unit is second. If you do not specify a value, the value will be zero which means "no time out". Zero timeout is not recommended: when something is wrong, a call to the log database should return promptly, so SuperLogging can send alert email to administrators.

You can use your favorite SQL database. Please contact us for log database schema for other database.

Install SuperLoggingLibrary and parameters

All applications which use SuperLogging need to access SuperLoggingLibrary. SuperLoggingEJB/SuperLoggingServlet needs to access SuperLoggingLibrary as well.

The casino example comes with a copy of SuperLoggingLibrary and SuperLoggingEJB for demo purpose. For production installation, you need to uninstall casino example, if it has been installed, and install SuperLoggingLibrary and SuperLoggingEJB/SuperLoggingServlet. See Install SuperLoggingLibrary and parameters for detailed information.

Start log database

To start the default log database server, go to the installed directory for log database and run

startLogDatabase.bat (Windows)
startLogDatabase.sh (Unix)
See Install, run and uninstall default database for installation details.

If you choose "Simple Install" when installing the program, a local log database is installed under Super home directory on client machine. The log database will be started when you start Super (the client) automatically. The local log database will not be automatically shut down when Super (the client) exits. You need the log database running when your server is running.

The local log database is a convenient arrangement for development and small business. For enterprise level production, you probably want to set log database on a different machine.

Maybe you want to use your favorite database instead of HypersonicSQL. If so, make sure the database is up and running.
 
Reconnect broken log database

If the log database connection is lost for any reason, an alert email will be sent out by SuperLogging. The administrator should fix the problem and make sure the log database is up and running again, then run Super (the client) to reconnect the database by opening the Reset Library Panel from menu Logging Manager. 
 
Support for other database as log database

SuperLogging uses standard ANSI SQL to access log database. SuperLogging can work with any ANSI SQL 92 entry level database. If you want to use other database than HypersonicSQL as your log database, please contact us.

The log database SQL scripts have been tested using the following database:

Security

Direct database connection

Users need sufficient privileges on J2EE server, the database and all underlying facilities. The system is protected by these accounts and passwords.

The parameters will be stored in a plain text file, named logDatabaseParameters with SuperLoggingLibrary. We assume that your computers are located in trusted areas and protected by passwords. There should be no any security problems. If you still have security concerns, you can leave password empty when you save these parameters. In this case, when SuperLoggingLibrary tries to establish a connection to the log database, SuperLoggingLibrary will use these database parameters to connect to the log database.  If the parameters are not complete or not valid, the connection will fail. You need to manually key in password using Reset Library facility to reset the log database without saving your password. See Reset Library Panel related information.

SuperLogging follows Security guideline for logins. If you do not save log database password, the connection to log database will fail when your J2EE server restarts. An alert email will be sent to administrators. An administrator need to go to Reset Library Panel where he/she can manually key in password without saving it.

 

   © Copyright 1999-2008 Acelet Corporation. All rights reserved.