Last updated December 23, 2013 18:52, by Ernie Rael
<h1> Dynamic Java Logging Management Wiki</h1>
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]] for including jLogMan in your app. The page [[todo]] discusses possibilities for future development. Bug reports and feature requests are welcome.
== Logger Table ==
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 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 have the root logger as their parent logger. If we take the 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 full package structured tree. The parent logger tree structure is determined from the ''Use Parent Handler'' column of the display table.
The image on the right has package nodes without loggers: java, java.awt and java.awt.focus along with some Class loggers.
jLogMan operates on a snapshot of the logging configuration, use Refresh action to take another snapshot.
=== Table columns ===
| The logging Class/Package tree structure. See below for a description of the icons.
| 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.
| 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 after doing these steps ('''except''' instead of a FileHandler, a ConsoleHandler is shown to keep it simple)
=== Tree Node Icons ===
Here are some words about the tree and icons.
| Logger for a Class. Leaf Node in the tree.
| Typically a Logger for a Package; this node has children. If a package logger has no children, then it will appear as a leaf node in the tree. Through Level inheritance, it may control the logging Level of its descendants.
| 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. Refresh removes this node.
| A Class logger which has been garbage collected. Refresh removes this node.
=== Remote Logging Configurations ===
jLogMan supports the display of a log tree based on a LoggingMXBean. This is imitted; 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.
| Expand Sub Trees
| Expand the sub tree under the cursor to expose all the descendant nodes.
| 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 [[#Handlers_and_Formatters|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<br/>logging configuration
| Does LogManager.readConfiguration. Clears the current configuration. Rereads the logger names.
| reset logging<br/>configuration
| Does 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 [[#ConfigurationDisplay|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.
| 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.
The ConfigurableFormatter can be used in your logging setup, see [[embedding]].
'''See the java.util.logging documentation if you don't understand this dialog.'''