| <?xml version="1.0"?> |
| <document> |
| |
| <properties> |
| <author email="BMarlborough@thoughtworks.com">Brad Marlborough</author> |
| <title>LogFactor5 Features Users' Guide</title> |
| </properties> |
| |
| <body> |
| <section name="LogFactor5 Features"> |
| |
| <h3><font color="#000099">Manage Log Messages</font></h3> |
| |
| <p>The Log Table pane shows the listing of LogRecords that have |
| been sent to the LogFactor5 appender. The newest log messages |
| appear at the bottom of the table. |
| </p> |
| |
| <p><img src="images/lf5_logtable.gif" align="absbottom" alt="Log Table" width="600" height="489"></img></p> |
| |
| <h4><font face="Verdana, Arial, Helvetica, sans-serif" size="3"><a name="levels"></a></font>Log |
| Level Selection </h4> |
| |
| <p>The LogFactor5 toolbar applies directly to the Log Table |
| area. Log levels can be toggled on and off to filter out |
| messages that you want to view or hide. Levels include FATAL, |
| ERROR, WARN, INFO and DEBUG. </p> |
| |
| |
| <p><img src="images/lf5_loglevels.gif" width="600" height="488" |
| alt="Log Levels"/></p> |
| |
| <p><a name="color"></a><b>Log Level Color Configuration</b></p> |
| |
| <p>To help distiguish the various log events displayed in the |
| LogTable, LogFactor5 allows users to set the colors of their |
| log events based on level.</p> |
| |
| <p><img src="images/lf5_colorchooser.gif" width="600" |
| height="489" alt="Log Level Color Configuration"/></p> |
| |
| <h4><a name="search"></a>Full Text Searching</h4> |
| |
| <p>The Log Table supports full text searching. To perform a |
| search, choose Edit->Find from the menu bar or CTRL-F and |
| then enter the text you want to search for. LogFactor5 will |
| find any strings that are an exact match for the string you |
| entered. Pressing F3 will find the next occurrence of the |
| string. |
| </p> |
| |
| <p><img src="images/lf5_search.gif" width="600" height="488" |
| alt="Full Text Searching"/></p> |
| |
| <h4><a name="views"></a>Log Table Views</h4> |
| |
| <!-- =========================================================== --> |
| <!-- In the next paragraph, changed category to logger, priority --> |
| <!-- to level, LogRecord to event. (Ceki) --> |
| <!-- =========================================================== --> |
| <p>The Log Table has three views; compact, standard and |
| detailed. The compact view only displays the Nested Diagnostic |
| Context (NDC), logger and message. The standard view is the |
| default view, and displays the level, NDC, logger and message |
| of the logging event. The detailed view displays, in addition, |
| the date, message number, location (i.e. the method that is |
| logging the message), thread description and the |
| throwable. The view selector on the toolbar switches between |
| the three views. Columns in the Log Table can be re-sized and |
| moved by interacting with the column headers. |
| </p> |
| |
| <p><img src="images/lf5_view.gif" width="600" height="489" |
| alt="Log Table View"/></p> |
| |
| <h4><a name="recorddetails"></a>Log Record Details</h4> |
| |
| <p>The Log Record Detail area displays all of the attributes of |
| the LogRecord which is selected in the Log Table. When a row, |
| or LogRecord, is selected in the Log Table, the complete |
| details of that LogRecord are displayed in the LogRecord |
| Detail area, independent of the view in effect. |
| </p> |
| |
| <p><img src="images/lf5_recorddetail.gif" width="600" |
| height="481" alt="LogRecord Details"/> |
| </p> |
| |
| <!-- ============================================================ --> |
| <!-- In the next 2 paragraphs, changed category to logger. (Ceki) --> |
| <!-- ============================================================ --> |
| <h4><a name="explorer"></a>Logger Explorer</h4> |
| |
| <p>The Logger Explorer area enables the filtering of incoming |
| log messages based on logger. If a logger is deselected |
| (no checkmark is shown next to it) then new messages on that |
| logger will not be displayed. The Logger Explorer has no |
| effect on log messages already in the Log Table. |
| </p> |
| |
| <p>The Logger Explorer displays loggers in a hierarchical |
| tree-like fashion. Loggers are identified with |
| dot-separated names similar to Java package and class |
| names. The name components are mapped to the levels in the |
| hierarchy in the Logger Explorer. For example, the logger |
| name org.apache.applications.log4j.InitUsing Log4JProperties |
| is displayed below: |
| </p> |
| |
| <p><img src="images/lf5_category_explorer.gif" width="600" |
| height="481" alt="Logger Explorer"/></p> |
| |
| |
| <h4><a name="selectloggers"></a>Selecting and Deselecting Loggers</h4> |
| |
| <p>When a logger in a hierarchy is deselected, no messages at |
| that level or below will appear in the Log Table. For example, |
| if just the first InitUsingMultipleAppenders logger in the |
| examples.InitUsingMultipleAppenders.InitUsingMultipleAppenders |
| logger is deselected, then messages with the logger examples |
| would be displayed in the Log Table, but messages with the |
| logger InitUsingMultipleAppenders.InitUsingMultipleAppenders |
| would be filtered and not displayed in the Log Table. |
| </p> |
| |
| <p>To quickly select or deselect loggers in the hierarchy, |
| the right-mouse button can be used to bring up the pop-up menu |
| displayed below. </p> |
| |
| <p><img src="images/lf5_deselectall.gif" width="600" |
| height="488" alt="Deselect All Descendants"/></p> |
| |
| <p><img src="images/lf5_selectall.gif" width="600" |
| height="488" alt="Select All Descendants"/></p> |
| |
| |
| <h4><a name="expandcattree"></a>Expanding and Collapsing the Logger Tree</h4> |
| |
| <p>You can also expand and collapse the hierarchy tree using |
| the pop-up menu displayed below.</p> |
| |
| <p><img src="images/lf5_expandall.gif" width="600" height="488" |
| alt="Expand Tree"/></p> |
| |
| <p><img src="images/lf5_collapseall.gif" width="600" |
| height="488" alt="Collapse Tree"/></p> |
| |
| <H4><a name="ndcfiltering"></a>NDC Record Filtering</H4> |
| |
| |
| <p>Log4j provides a lightweight technique for stamping log |
| requests initiated from the same client within a multithreaded |
| system. The Nested Diagnostic Context (NDC) provides an easy |
| way to differentiate logging output of one client from |
| another. The NDC is also useful for differentiating log |
| messages being output by different members of a large |
| development team building an application on the same |
| server. To improve the sorting of potentially thousands of log |
| records being output from multiple clients, a NDC filter has |
| been provided. To use the NDC filter, select the Edit menu |
| item and choose 'Sort by NDC'. Fill in the name of the NDC you |
| would like to filter on. All records containing the filter key |
| word will be displayed in the Log Table. To restore all of the |
| log records use the Edit -> Restore all NDC's. You can also |
| use the Edit->Find feature to locate NDC's without removing |
| log records from the Log Table. Furthermore, you can use the |
| Configure->Save feature to persist the last NDC filter key |
| word that was used. Note however that restoring all NDCs will |
| effectively erase the NDC filter key word. Refer to the <a |
| href="#configuration">Configuration section</a> below for more |
| information on saving NDC filter key words.</p> |
| |
| <p><img src="images/lf5_ndc_filtering.gif" width="600" |
| height="488" alt="NDC Filtering"/></p> |
| |
| |
| <font color="#000099"><h3>Read Log Files</h3> |
| </font> |
| |
| <h4><a name="readfile"></a>Read a File</h4> |
| |
| <p>LogFactor5 supports reading in log files that were created |
| using log4j's RollingFileAppender. The benefit of this |
| feature is that developers who run utilities like Ant to test |
| their applications can now view their log files off-line |
| (i.e. after their application has completed the test and the |
| JVM has shut down). Reading log files currently only works for |
| files written a LogFactor5's unique ConversionPattern. For |
| more information on setting the LogFactor5 conversion pattern, |
| please see the OpeningLogFiles example. To open a file and |
| read it into LogFactor5, you need to start the logging console |
| using the StartLogFactor5Console.bat file provided in the bin |
| directory. Once the console is open, choose File->Open from |
| the menu at the top of the GUI. |
| </p> |
| |
| <p><img src="images/lf5_openfile.gif" width="600" height="488" |
| align="absbottom" alt="Log Table"/></p> |
| |
| <h4><a name="readurl"></a>Read a File From a URL</h4> |
| |
| <p>LogFactor5 supports reading log files created using log4j |
| from a URL. Having the ability to open log files on a remote |
| server provides the ability for multiple developers working on |
| the same application to view log files independently. It also |
| gives developers the ability to view log files both internally |
| and from remote locations. Reading log files currently only |
| works for files written a LogFactor5's unique |
| ConversionPattern. For more information on setting the |
| LogFactor5 conversion pattern, please see the <a |
| href="example7.html">OpeningLogFiles</a> example. To open a |
| file and read it into LogFactor5, you need to start the |
| logging console using the StartLogFactor5Console.bat file |
| provided in the bin directory. Once the console is open, |
| choose File->Open URL from the menu at the top of the GUI. |
| </p> |
| |
| <p><img src="images/lf5_openurl.gif" width="600" height="488" align="absbottom" alt="Log Table"/> </p> |
| |
| <p><a href="#top"><font size="2"><< Return to Top of Page >></font></a></p> |
| |
| <font color="#000099"> <h3>Configuration</h3></font> |
| |
| <h4><a name="configuration"></a>Save Configuration Information</h4> |
| |
| <p>LogFactor5 allows you to save your current |
| configuration. When you choose the Configuration->Save |
| option from the menu at the top of the GUI, the loggers and |
| levels that you currently have selected, along with the last |
| NDC filter key word used (assuming 'Restore all NDC's' has not |
| been selected), are saved to your local file system. This |
| means that the next time you start up the console you will not |
| need to reselect the loggers, levels, and NDC filter that you |
| would like used for filtering. |
| </p> |
| |
| <p>LogFactor5 also allows you to remove your saved |
| configuration, and to configure the maximum number of records |
| that will be displayed at any time in the logging |
| console. Setting the maximum number of records to display |
| allows you to optimize LogFactor5's performance for your |
| system. The maximum number of records can also be configured |
| via a log4j properties file. |
| </p> |
| |
| <p><img src="images/lf5_configure.gif" width="600" height="488" align="absbottom" alt="Log Table"/></p> |
| </section> |
| </body> |
| </document> |