This library provides a GUI tool for run time Java Logger management; it can easily be included in any swing application. It is a tool for working with logging that has already been incorporated into a software product. It provides dynamic, run time, control over logging. A developer can create loggers and handlers, in addition to changing logger and handler levels. You can specify that a Configuration that you create for a particular task be applied at application startup. A Configuration can be saved to a file.
Using this tool, there is no longer a need to modify application startup and configuration files to adjust logging levels when tracking down particular issues. And since it is dynamic, if a situation arises while the application is running then you can turn on logging without having to restart the app; at run time you can create a logger/handler to send all,or a subset of, log data to a file.
This page show how to use the jLogMan UI. You can try out jLogMan in a test app by doing "java -jar jLogMan.jar" after unzipping the jLogMan.zip or if you check out the source you can do "ant run" in the LogMan directory. A NetBeans plugin is available through the Plugin Manager.
See embedding in an application for including jLogMan in your app. The page todo discusses possibilities for future development. Bug reports and feature requests are welcome.
__TOC__
jLogMan "Loggers" table
The Loggers table is the primary UI for jLogMan. View loggers and handlers and change logging levels for loggers and handlers by clicking on the table. Through popup menus create new loggers and handlers; the popup menus are described at Actions and Configuratinons.
Two logging hierarchies
In the javadocs for java.util.logging.Logger it states
Logger names ... should normally be based on the package name or class name of the logged component...
For convenience, this document assumes that each logger is associated with either a package or a class; however that is not required. Logger names form a hierarchical dot-separated namespace.
There are actually two tree structures to consider.
Loggers and Logger parents
Loggers and Logger parents usually form a very shallow tree. Consider if all logger names are a class then the root logger is the parent of all of these loggers. For example, given class loggers a.b.C1, a.b.c.C2, a.b.c.C3 and a.b.d.C4, these four loggers have the root logger as their parent logger; a two level tree. Note that the logger and logger parent tree structure is determined from the last column, Use Parent Handler, of the table.
java package structure
If we take the java package structure into account, then a, a.b, a.b.c and a.b.d are tree nodes; these nodes do not have associated loggers. jLogMan displays the package tree structure in the first column.
The image on the right has package nodes without loggers: java, java.awt and java.awt.focus along with some class loggers. Under java.awt there are two class loggers and under java.awt.focus there are three Class loggers.
In the example below. jLogMan is used to create some package loggers on java.awt and java.awt.focus to control the output from these class loggers.
jLogMan displays a snapshot
jLogMan operates on a snapshot of the logging configuration, use Refresh action to take another snapshot.
jLogMan table columns
Column
Description
Loggers
The logging Class/Package tree structure. See below for a description of the icons.
Level
The logging Level assigned to the row's logger or handler. It is empty if the Leve is set to null (inherit). Click the cell to edit the Level. The cell is dark, and can not be edited, if the row is neither a logger nor a handler.
Effective
The effective logging Level for the row's logger. Typically a logger's Level is set to null, which means the logger inherits from it's parent logger.
Use Parent's Handler
For a logger, there is a checkbox for the useParentHandler property and the name of the parent logger. For a Handler there is the type of handler and its formatter.
Example
Let's say there is an issue with the awt focusing and you suspect it is in the KeyboardFocusManager Class. To investigate it, you want to turn on FINE logging for all the loggers in java.awt, and FINER logging for those in java.awt.focus and FINEST for KeyboardFocusManger. Finally, you want to send this logging to a file using the XML formatter.
Do this with jLogMan by creating loggers on java.awt and java.awt.focus and then assigning the Levels you want; also set the Level for KeyboardFocusManger. Since all the Class loggers in this area inherit their Level, the newly created package loggers control their Level. Next create a Handler. The image on the right shows the table after these things are done.
Notice which Levels are now set and the effective levels. The Use Parent's Handler column states the parent logger name, see how it has changed from (root). Information about the table row with focus is in the text field at the top; for a Handler it includes the handler properties as determined by reflection display as constructor.
These operations are done through the popup menu and cell editing. The section Actions, find it below, show how to perform these operations on the table.
On the right is result of the Display Configuration, action in the Configurations sub-menu, after doing these example steps (except instead of a FileHandler, a ConsoleHandler is shown to keep it simple)
This is similar to how configuration information is saved in storage for the save operations in the Configurations sub-menu.
Tree Node Icons
Here are some words about the tree and icons.
Icon
Description
Logger for a Class. Leaf Node in the tree.
Typically a Logger for a Package; this node has children. Through Level inheritance, it may control the logging Level of its descendants. If a package logger has no children, then it will appear as a leaf node in the tree.
Handler for the Logger which is its imeadiate parent node.
A package node with no associated logger.
A package logger which has been garbage collected.
A Class logger which has been garbage collected. The refresh action removes this node.
Remote Logging Configurations
jLogMan supports the display of a log tree based on a PlatformLoggingMXBean. This is limited; you can only change levels. It is not well tested.
Actions
Clicking on a cell in the Level column brings up a combo box to set the Level of the row's logger. The Level can also be set through the popup menu.
Context sensitive actions in the popup menu are enabled according to the selected cell. For logger and handler related actions, place the cursor over the tree (the first column) when bringing up the popup menu.
Action
Description
Expand Sub Trees
Expand the sub tree under the cursor to expose all the descendant nodes.
Configurations
Bring up the configurations sub menu, see below.
Set Level
Set the Level to the level selected from the sub menu.
Create Logger "<name>"
Create a logger under the package node at the cursor. <name> is the name of the logger to create.
Create Logger by Name
Bring up a dialog with a text field. Enter the name of the logger to create. The field is initialized to the name of the tree node.
Create Handler
This action brings up a dialog to create an arbitrary handler for the logger under the cursor. There is an image of the dialog below.
Configure Formatter
The action is enabled if the handler under the cursor has a ConfigurableFormatter. It brings up Configurable Formatter Paramteters. See it as a subpanel of the Create Handler dialog below.
Remove Handler
Removes the handler under the cursor from the logger.
Refresh Logger Tree
Read the names of all the loggers from the LogManager.
Garbage Collect
Run the system garbage collector.
Reinit/reread
logging configuration
Do LogManager.readConfiguration. Clears the current configuration. Rereads the logger names.
reset logging configuration
Do LogManager.reset. Clears the current configuration. Rereads the logger names.
Configurations
A collection of changes and additions made using jLogMan is called a configuration. The Current Configuration is all the modifications made to the current logging configuration.
A configuration can be displayed; there is an example of a configuration display in a previous section. Handler names in a configuration display are tagged with either @usr-<digit> or @pgm-<digit>. The @pgm tag is for handlers created by the application; @usr is for handlers created by the user through jLogMan.
If Apply Configuration at Startup is set then during jLogMan initialization (usually at application startup) the Current Configuration, when the application last terminated, is applied. Note that if an error occurs, then the Current Configuration is copied to the Previous Configuration and the Current Configuration is cleared.
Action
Description
Apply Configuration at startup
Boolean. When checked/set the Current Configuration is applied when jLogMan is initialized.
Display Current Configuration
Display Previous Configuration
Display File Configuration
Clear Configuration
Undo the modifications for the current configuration.
Apply Previous Configuration
Clear the current configuration and apply the previous configuration. The current configuration becomes a copy of the previous configuration.
Apply File Configuration
Clear the current configuration and apply the named file configuration.
reApply Current Configuration
First clear the current configuration.
Save Current to Previous
No modifications are made to the loggin configuration.
Save Current to File
Save Previous to File
Handlers and Formatters
The Create Handler dialog allows an arbitray handler and formatter to be created using stander jre classes; in addition there is a ConfigurableFormatter that is available. Depending on the Handler and Formatter type selected with the radio buttons, different parameter sub-panels are displayed to allow customization, the customization is usually the arguments to a constructor.
