|
|
Right Java tools for J2EE, Web Service, Grid and more |
| |Home | Products | Documents | Downloads | Purchase | Support | Company | Partners | Contact | |
SuperLogging Tutorial
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.
Welcome to SuperLogging! This tutorial is based on a simple casino game example. Please see Casino game for description of the game.
By the way, you can press the F1 key to access context sensitive help system from any window throughout the whole program.
Note: It is recommended that you run your J2EE server and Super on the same machine (localhost) for this tutorial. Your screen may or may not be exactly the same with our screen shots, especially when the values change. Remote deployment may or may not work with this example.
Click the following links for related information:
1. Log statement
When you want to log, you must call log methods in your EJB, JSP or helper classes. The Log method API is on com.acelet.logging.Logging. To prevent vendor lock-in, an open source wrapper is provided as com.acelet.opensource.logging.Alog. You can use log methods from either of these classes. We use both of them in our example, CasinoExampleEJB.java. Also see Log methods for more information.
For our tutorial, when we run CasinoExampleEJB, some log
methods are called from that example and log message records are generated. We will
show you how to monitor and audit those records. Let us start now.
2. Go to the main menu. Click on the Modules > SuperLogging > Run Example to run the example.
3. The CasinoExample Panel appears. The CasinoExampleEJB is running on your J2EE server, simulating a casino game. The CasinoExample Panel repeatedly gets a lucky number from the server.
4. Now, we want to see if there is any log record generated by this example.
Go to the main menu again. Click on Module > SuperLogging > Tail to open the Tail Panel.
5. The Tail Panel appears. It shows the latest log records. This panel automatically refreshes itself promptly.
At this point, there is no log records, because no class has been registered.
The CasinoExample is running. We want to see log records from it. you need to register CasinoExampleEJB class. When the class is registered, the SuperLogging will generate log records, which is the information source for the Tail Panel and tracing. To register this class, go to the main menu. Click on Module > SuperLogging > Register to bring up the Register Class Panel.
6. The Register Class Panel appears. Let's click the Add button.
7. The Select Registered Class Panel appears. Let's click the Browse button.
8. Double click examples directory.
9. Highlight CasinoExampleEJB.java, click the Add button.
Confirm the Full class name by clicking the Ok button.
10. Now the Register Class Panel shows the registered class examples.CasinoExampleEJB. Click the Close button to close the Register Class Panel.
11. Now you can see some log message records on the Tail Panel, with syntax highlighting. Your screen should be similar to the one shown below. On our screen shot, the log message records come from two lines: CasinoExampleEJB.java:58 and CasinoExampleEJB.java:61.
12. Let's click on a line with CasinoExampleEJB.java:61, the Source Code Panel shows up and the selected line 61 is marked with ">" sign. The line number also appears on the top of the panel.
13. Let's close this Source Code Panel by clicking on the cancel button on top-right corner. We come back to the Tail Panel. Let's see the other functions of the Tail Panel.
There are a few buttons on the top of this panel. Let's see the simple ones first. The Stop button stops the tail operation and stops all network traffic related to it. When Stop button is clicked, it becomes Go button. The Go button restarts the tail operation. Stop and Go are toggled buttons. The Clear button clears the main text area. The Close button close this panel and remember the size of this panel, so when the Tail Panel is open the next time, it will be in the remembered size.
Now, we want to see what the Preference button will bring to us. Let's click on it.
14. The Tail Preference Panel appears. The Pace is the interval of two tail operation. The Batch size is the number of log records shown. Note: this is a suggested value. If there are fewer new log records, the log records shown may be less than this value. The Query timeout is the timeout value for tail operation. These parameters and be changed at any time. They take effect immediately.
15. Let's go back to the Tail Panel again.
The Set button is for setting filter to filter unwanted log message. Let's click on it.
16. The Filter Panel appears. This is an advanced topic.
The Where clause is for specifying the WHERE clause for the tail operation. If you type:
WHERE msg like 'd=%'
the Tail Panel will show the log message from line 58 only. And the WHERE clause will be shown on the Filter field.
17. All log method calls can remain on production releases. You can dynamically filter out unwanted log message be dynamically reconfigure SuperLogging. Dynamic registration is one of the reconfiguration. We have used the Register Panel and know if a class is not registered, no log message record will be generated and the performance penalty will be minimum.
Now let us go to the main menu and click on Module > SuperLogging > Attribute to open the Attribute Panel.
 |
The Attribute Panel is for configuring the Logging. You can change attribute settings. To make trace facilities work, the DATABASE must be selected on Log device and Error device. After highlighting DATABASE, click Ok button . |
|
The Threshold is another attribute of SuperLogging. It is against log level argument in your log method call. All log statements whose log level is lower than this value will be filtered out. When you program, you should selectively set your log levels. |
 |
The Mode has three alternatives: Conditional, Quiet and Verbose. If you choose Quiet, no log message record will be generated unconditionally. Verbose, on the other hand, will unconditionally generate all log message records. Conditional will generate log message records if the class is registered and the log level is equal or higher then the Threshold here. |
Each time you change the attribute, a logging record is written on your log device, recording the new attribute setting.
18. In the above example, SuperLogging looks like a desktop application. Actually things are not that simple, because SuperLogging is designed for Distributed Computing Environment. We are in multi-tier enterprise system.
Here is how things work.
Super GUI windows are the client side programs. SuperLoggingLibrary is on the remote side. Even it is on the same machine, it is still considered as a remote system, because the library and the J2EE server runs in different JVMs (Java Virtual Machines), runs in different memory spaces. SuperLoggingEJB (we have deployed it at the first time we use Super) is the bridge between our GUI windows and SuperLoggingLibrary. When we change the attributes using the GUI windows, Super communicates with SuperLoggingEJB, which accesses to SuperLoggingLibrary. The SuperLoggingEJB changes attributes of SuperLoggingLibrary.
What will happen if the connection between SuperLoggingLibrary and log database is broken? No one is sitting in front of the J2EE servers to watch it. SuperLogging provides Alert and Alarm facilities to check it. If there is any connection problem, an alert mail will be sent to system administrators. If you want to know about the Alert and Alarm Facilities, go to the Alert and Alarm Facilities Tour to get more information.
If you do not fully understand multi-tier issues, you can still use Super, just as if it were a desktop application. We will discuss this kind of issues later again.
This is our basic logging introduction. There are more features below.
19. Now, let's see how to manage log database. Go to the main menu again. Click on Modules > SuperLogging > Parameter > View parameter on server. The View Parameter Panel will appear.
The parameters shown above are downloaded from the J2EE server side. Note: the Password field is empty. For security reasons SuperLogging never downloads the password from the server side to the client side.
Let's click on the Close button to close this window.
20. If you want to use your favorite database, you need to modify log parameters. Go to the main menu again. Click on Modules > SuperLogging > Parameter > Edit parameters on jar.
This panel allows you to specify new parameters for SuperLoggingEJB and SuperLoggingLibrary. Parameters can not dynamically reconfigured. The saved new jar files need to be deployed. See Install SuperLoggingLibrary and parameters for detailed information.
There is something we should consider. When you key in password, the password will not show literally. When you save it, it will be saved as plain text on your local J2EE server side, where is trusted location. There should be no any problems and safe. If you still have security concerns, you can leave the Password field empty when you save these parameters. Then you need to Reset Library to activate it.
21. If you do change log parameters. You need to reset SuperLoggingLibrary to make those parameters effective. You should go to the main menu and click on Modules > SuperLogging > Reset Library. The Reset Library Panel will appear.
 |
Key
in password, click on Ok, answer a confirm window, then the library will
be reset.
See Reset Library for more formation.
|
You may ask: why things are so complicated? The answer is very simple: we are in Distributed Computing Environment. Remember we have discussed earlier?
21. Let's introduce the concept of scope. This is an advanced feature.
Again, we are in Distributed Computing Environment. There are maybe many server machines. There are maybe many J2EE application servers run on each machine. These application server works together as one cluster. All those application servers run in their own JVMs and memory spaces. SuperLoggingLibraries and your applications run in those JVMs. How can we keep all of them in sync with the same configuration?
The simple and effective answer is to read SuperLogging configuration information from the central database each time you call a logging statement. In this case the scope of configuration is Dynamic (global-dynamic). It should be good for most cases, but with performance penalty. If your application is not too busy, this is a viable solution, especially with low-cost, high-speed hardware.
Maybe we can read the configuration information when application server starts and keep it in memory and never change it. This scope of configuration is Static (global-static). The performance penalty is low. But it is not flexible. The configuration values can be changed at application server restart time only. This is what most logging API or system do. SuperLogging finds a way to make it flexible. When you need to change the configuration information, you can upgrade scope to Dynamic using JMS to regain flexibility. All instances of SuperLoggingLibraries will get the JMS message and upgrade their own configuration information. After the configuration is changed, you can set the scope back to Static and regain performance.
I am greedy. Is there a better way? Yes, it comes Smart scope. It is the combination of all above. When you change configuration information, all instances of SuperLoggingLibraries will automatically download new configuration, then keep it in memory until it is informed to download again. This scope is very flexible with minimum performance penalty.
The last scope is Singleton. If you have only a single J2EE server its the best. But it can not keep multi-servers in sync, so it is good for one single J2EE server only.
See Scope for more information.
All scope changes can be done using the Scope Panel by going to the main menu and click on Modules > SuperLogging > Scope. The Scope Panel appears.
 |
See the Scope Panel and Change Scope for more information. |
This is our Super Logging tutorial. You can get more information from SuperLogging. If you have not see Alert and Alarm Facilities Tour, it it the time to do so.
Appendix
The main differences between SuperLogging and other loggings
SuperLogging fully supports clustering: