|
|
Right Java tools for J2EE, Web Service, Grid and more |
| |Home | Products | Documents | Downloads | Purchase | Support | Company | Partners | Contact | |
SuperLimpid is based on open source LimpidLog from Acelet.
Contents
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.
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.
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:
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.
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:
See Manager windows for details.
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 will be called and returned quickly. Not much time wasted. Especially, because most of classes are loaded when the system starts. After that, 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.
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.
The records of logging go to LogProxy. A LogProxy can be:
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 in the current directory at start up time. The file is a properties file. If the file exists, all properties specified will be loaded and overwritten existing properties.
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 |
| 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 |
| fileLogMachineReading | Indicates should or not to use a format for machine reading when logProxy is 'file' | true |
| 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 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 |
| useLocalVariableName | Indicates should or not to use literal name for local variables. | true |
LimpidLog will ignore invalid options.
The Java used for the tests are Sun's Java version 1.5.0_08, unless state otherwise.
For machine reading format, the delimiter for columns is ASCII zero. It may look like a funny character.
How to test CasinoExample: Tested under Weblogic 9.1 using examples.CasinoExampleEJB from SuperLogging. Run the example from the main menu > Modules > SuperLogging > Run example. Before register the class, nothing logged from the class. When add examples.CasinoExampleEJB the following log message printed out:
Tested register-deregister-register-deregister..: working.
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.
LimpidLog can be dynamically, programmatically reconfigured. It is very simple:
new com.acelet.opensource.limpidlog.ClientTalk(hostname, port).sendCommand(your_command);
For example,
new com.acelet.opensource.limpidlog.ClientTalk("localhost", 9876).sendCommand("add examples.CasinoExampleEJB");
For version 4.00: