|Home | Products | Documents | Downloads | Purchase | Support | Company | Partners | Contact |
LimpidLog

Contents


Overview

LimpidLog is a revolutionary logging system. You do not need to hard code log statements. At runtime, you can register a class of interest and the system will log all important information about the class. When you are done, you can de-register the class and the class will not generate any log information anymore.

LimpidLog is for J2EE logging, Java EE logging and Java Logging (Java logging for standalone Java application). LimpidLog supports J2EE applications,  Java EE applications and standalone Java applications.

LimpidLog supports redefinition. You can dynamically register and deregister a class. This is especially important for J2EE: at the time you want log, the class probably has been loaded already.

LimpidLog is an open source project hosted at: SourceForge.net.

If you get this page from downloaded software, check out http://www.acelet.com/limpidlog to see if that is a newer version.

LimpidLog supports Netbeans with GUI management as Netbeans plug-in.

How does it work

LimpidLog uses java.lang.instrument.Instrumentation of Java to log, as a Java Agent. When you register a class for logging, LimpidLog uses a bytecode sidenoting to add logging information to the class. Then LimpidLog call Java JVM to redefine the class with added log information. JVM will reload the class. Then, when the class is executed, added logging will perform. When you de-register the class, LimpidLog will redefine the class using the original class bytecode and all added code for logging will be gone.  

LimpidLog does not allow you to set "break points": your application runs uninterruptedly. Other applications, such as LimpidDebugger, use data which generated by LimpidLog and set "break points". That "break points" are not at your application runtime. That "break points" are breaks for reading or replay, not for execution.

Prerequisite

The application must run using Java 1.5 or later, not 1.4.

The GUI management of LimpidLog can run using Java 1.4, 1.5, or later.

What information will be logged

LimpidLog logs the standard information and standard format for all Java classes.

LimpidLog logs when an execution event happens. Currently the following event are supported:

How to use

LimpidLog is used with Java (JVM), not directly used with your application:

When you run Java, you need -javaagent option. At that point, you specify LimpidLog as a -javaagent option. LimpidLog will be called by Java.

Procedure

1. Run your application with -javaagent option.

2. Run GUI management tools.

If you give applicants option and properties option, the LimpidLog manager may or may not be necessary.

For a production environment, you may or may not ever encounter a bug in your applications. But if you want to have an opportunity to use LimpidLog when needed, you need to run your application with -javaagent option, to make it LimpidLog-enabled. See The performance price to pay for idle LimpidLog for related information.

Run your application with -javaagent option

When you start your java program, for example WebLogic server, you need to give an option

-javaagent:limpidlogXXX.jar=port=<port_number>

where XXX donates for the version number. <port_number> is the port number you want to use. For example, if you download LimpidLog version 1.00 and want to use port 9876, the option will be:

-javaagent:limpidlog100.jar=port=9876

You will see LimpidLog version on your screen:

LimpidLog 4.00 Bytecoder1. Acelet. LGPL license. ASM from ObjectWeb.

The log data will be recorded into log files. The log files will be on your working directory. The file name is limpidlogXXXXXXXXXXXXXX.log, where XXXXXXXXXXXXXX  is the time stamp when the file is created. Example: limpidlog20071216134332.log.

You may want to give more options. See Configuration Options for more information.

Example for Tomcat

Modify startup.bat (not catalina.bat) and add:

  set JAVA_OPTS=%JAVA_OPTS% -javaagent:c:\myDir\limpidlogXXX.jar

Example for JBoss

Modify run.bat and add:

  set JAVA_OPTS=%JAVA_OPTS% -javaagent:c:\myDir\limpidlogXXX.jar

Example for Weblogic 9 and 10

Modify startWebLogic.cmd adding:

set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:limpidLogXXX.jar

where limpidLogXXX.jar must be under current directory, or the absolute path is included.

Run GUI management tools

At runtime, open a new Operating System console to run the manager of LimpidLog:

java -jar limpidlogXXX.jar 

The GUI manager allows you to dynamically register and deregister classes. It does not allow you to set "break points": your application runs continuously.

The Java which runs LimpidLog manager does not have to be the same version of Java which runs the application in question. You can run it on any computer which can communicate with your application (the host name and port are accessible).

You will see:

If there is a plugin of LimpidLog at the runtime, the plugin will be automatically detected and shown:

See Document of LimpidLog Windows for details.

Configuration Options

Options are specified at start up time, as part of the -javaagent option of Java.

-javaagent:limpidlog400.jar[=options] 

See Description of java.lang.instrument for more information.

Every option has a default value. The default value will be overwritten by the value in the properties file, if the option is specified there. Then, will be overwritten by command-line option, if the option is specified there.

LimpidLog looks a file named limpidlog.properties on the current directory at start up time. If the file exists, all properties specified will be loaded and overwritten existing properties. The file is a properties file. Each line of it is a key-value pare. The keys and values must be exactly spelling.

If you want use a different name for the properties file, you need to specified as a -javaagent option. For example:

-javaagent:limpidlog400.jar=properties=Mine.properties

In this case, LimpidLog will use Mine.properties as the properties file.

Option table

Option Description Default value
applicants The name of a file for applicants. Each line in the file is a full class name, which will be an applicant who wants to be redefined for logging before be loaded. limpidlog.applicants
bytecoderClass The full name of the implementation of limpidlog.Bytecoder. limpidlog.asm1.Bytecoder1
databaseDriverName The JDBC driver name of database which stores log data when the option logProxy is database.  
databaseUrl The URL of database which stores log data when the option logProxy is database.  
databaseUserName The user name of database which stores log data when the option logProxy is database.  
databasePassword The password for the user of database which stores log data when the option logProxy is database.  
debug Indicates if general debug information should be logged. This is for debugging inside of LimpidLog. false
fileLogBaseName The base name for logging to a file. limpidlog
fileLogMaxSize The maximum size of the log file. When the file is bigger than this, a new log file will be used. Unit: Meg. 100 M
logOnArgument Indicates should or not log method argument true
logOnField Indicates should or not log on field assignment true
logOnIncrease Indicates should or not log on event of increase true
logOnReturn Indicates should or not log on event of returning from a method true
logOnStore Indicates should or not log on event of store. true
logProxy The full name of the class which implements limpidlog.LogProxy. It can be keyword console, database or file. console
noLimpidlog Indicates should or not be interested in logging of classes of LimpieLog. true
noJava Indicates should or not be interested in logging of Java classes. true
noSun Indicates should or not be interested in logging of classes starts with "sun.". true
port The port number used for agent and manager of LimpidLog. 9876
properties The name of properties file of LimpidLog. limpidlog.properties
queryTimeout The query timeout of database which stores log data when the option logProxy is database.  
useLocalVariableName Indicates should or not to use literal name for local variables. true

LimpidLog will ignore invalid options.

Example of the properties file:

logProxy=database
databaseDriverName=org.hsql.jdbcDriver
databaseUrl=jdbc:HypersonicSQL:hsql://localhost:23536
databaseUserName=acelet
databasePassword=acelet

The performance price to pay

The performance price to pay for idle LimpidLog

If you do not register any class, the price for the idle LimpidLog is:

1. Each time a class is loaded, a method of LimpidLog will be called and returned quickly. Not much time wasted. Because most of classes are loaded when the system starts, so the impact is very small. After the JVM started, loading will not happen very often.

2. LimpidLog keeps all loaded class names in memory. This piece of memory is relatively small compare to your program (the size of a name is much smaller than the size of the class). The reason to keep this piece of memory is for performance.

3. The memory for LimpidLog itself is about 50K. Very small.

The performance price to pay for a registered class

You can dynamically re-configure LimpidLog. Log messages will be recorded only when the interested class is registered and the events are selected. You can choose fewer events. Of course, the more event you choose, the more details you will get, but the slower.

If you do register a class, the price is:

1. For every event, there will be a line (for file) or a row (for database) written.

2.  Database is more expensive than file, because there will be a cross-wire access (remote access). Write to a file is faster. When you need to debug, you need to migrate from file to database, that time will be spend off-line. So, choose persistence type as file may be a good idea for single application. If the issue is related to multi-server, of cause, database will be better type of persistence.

3. When LimpidLog writes a line or row, the number of bytes, GENERALLY, do not make much difference on the speed, due to the use of cache/register by computer systems. The cache usually is 512 or 1024, so write one byte or 512 bytes may take the same time.

In later releases, when LimpidLog is idle, it will be 100% idle. If you do not use it, JVM will not call it. No wasted time. Only the 50K memory will be "wasted". At the time you want log, you can activate LimpidLog from the GUI manager.

The size of transformed classes

The transformed classes are much bigger than the original ones. Most of transformed classes are 2.5-3.1 times as the size of the original. We have seen 1.5 times, but not seen 3.5 times or bigger.

Log proxy

The records of logging go to LogProxy. A LogProxy can be:

Limitation

Tested platforms

The Java used for the tests are Sun's Java version 1.5.0_08, unless state otherwise.

Tested register-deregister-register-deregister..: working.

Thread safety

LimpidLog is thread safe.

LimpidLog records data thread-safely. Your application can run in multi-threading environment.

LimpidLog manages run time configuration safely. But this issue is not relevant. There should be one person working on the configuration at the same time. If there are more than one person reconfigure the system, there will be logical conflicts: one wants to register a class, the other wants to de-register that class. LimpidLog is not a consumer product. When logging is needed, there should be only one person from the response team to work on at a time.

Programmatically configure

LimpidLog can be dynamically, programmatically reconfigured. It is very simple. Just call the method:

 public Object sendCommand(String action, Object argument) throws Exception {
 

For example,

new com.acelet.opensource.limpidlog.ClientTalk("localhost", 9876).sendCommand("register", "examples.CasinoExampleEJB");

See the following source code files for details:

Known issues

For version 4.0:


   Copyright Acelet Corporation. All rights reserved.

 

Site Map Home Products: Acelet-Filer Super Suite Audit Log Easy EJB Easy JMS Easy JMX Easy Webservice Limpid Debugger Super Environment Super Log SuperStress Super Scheduler Super Log Reader Super Watchdog Super Workflow OpenSource Limpid Log Freeware Mortgage software Downloads Purchase Support Consulting Company Partners Contact us


© 2014 Acelet Corporation.