Chainsaw and RI Logging
Chainsaw is a power tool that cuts through rubble to identify and isolate interesting RI log messages, supporting filtering, colorizing and searching of events using a simple expression syntax. For more information on Chainsaw see the Chainsaw home page (the version of Chainsaw on the home page is outdated, use the version attached instead).
[http://logging.apache.org/chainsaw/index.html]
See attached chainsawdemo.zip for an avi demo of installing and using Chainsaw
See Chainsaw screenshots below
Installation and Configuration
Chainsaw is a Java Swing application (can be ran on Windows, Linux, Mac OSX). Chainsaw accepts events from log4j 'receivers', which know how to process events from a variety of sources (a file, database, the network). The receiver configuration can be defined from the Chainsaw UI or in an XML configuration file.
The attached example receiver configuration files (one for Java stack logging, one for platform logging) define a 'file-based' receiver which can parse and tail RILog.txt. The receiver will continue to tail RILog.txt, even if the file is deleted and recreated due to passing -deletelog to runRI.sh.
To install Chainsaw:
- download the standalone-zip attachment
- extract the zip file
Configuration files
The file-based receiver uses a 'logFormat' string to parse the log file contents using regular expressions, so the 'level' field in the log file ends up in the 'level' column, the 'logger' field in the log file ends up in the 'logger' column.
RI Stack log4j logging is 'nested' inside the Platform log4c log messages, so to parse the log4j logging output (provides ability to define queries using the log4j loggers and levels), a Stack log4j-specific configuration file must be used. A platform-specific configuration file will provide the ability to define queries using the log4c loggers and levels, but the log4j logging output (the entire stack log4j message, including the level and logger defined the the stack Java code) will be included in the 'message' field.
Two configuration files are attached - a RI Stack (Java-specific) configuration and a platform configuration.
If you want the Stack Java logging output in Chainsaw, use:
- chainsaw-stack.xml
If you want Platform logging output in Chainsaw, use:
- chainsaw-platform.xml
To configure Chainsaw to tail the RILog.txt file:
- download and modify the configuration you want to use
- modify the fileURL parameter to match the URL to RILog.txt you wish to tail
- On Windows, the fileURL parameter will look like: file:///c:/path/to/RILog.txt
- On Linux and OSX, the fileURL parameter will look like: file:/path/to/RILog.txt
- the logFormat parameter CAN be modified if you need to process log files in a different format (from third parties) or if you need to modify log4crc or log4j.properties layouts
- no other fields probably need to be modified - once you start Chainsaw you can see documentation for the file-based receiver in the Help/Receiver JavaDoc menu
- Start Chainsaw from bin/chainsaw or bin/chainsaw.cmd as appropriate (or create a shortcut)
- A 'No receivers are defined' dialog will be displayed, select the 'use an existing receiver configuration' radio button, and press the 'browse' button
- Select the configuration file you modified
- Click the 'don't show this again' check box - the next time Chainsaw is started it will use this configuration automatically
To verify the installation and configuration do the following:
1. Start RI and the RI (order doesn't matter) 2. A new tab should appear in the Chainsaw UI - the tab name should be the path to the RILog.txt file 3. As events are added to RILog.txt, events should appear in the tab's table as additional rows
Chainsaw features
Chainsaw supports colorizing, filtering and search using a simple expression syntax, and persists all application-wide and per-tab settings - a tab should look the same when Chainsaw is restarted as it did when Chainsaw was closed. The expression syntax is described in the Tutorial panel (available from the Help menu or Welcome tab)
'Unknown' logger
The receiver logFormat value is configured to know how to parse Java stack logging (format defined in log4j.properties). This means the Java loggers will display in the logger tree, and events which came from the Platform will still show up in the table, but will be associated with the 'Unknown' logger. A configuration file which can parse Platform logging will be attached shortly.
Example expressions which can be used to define color rules, search and filter expressions
- level > info
- exception exists
- msg ~= 'select service' || msg ~= 'posting'
- prop.log4j.marker exists
- logger ~= servicecontext || logger ~= presentation
Chainsaw UI
The Chainsaw UI is broken up into six areas:
- Tabs
- Events are routed to tabs based on values found in the event, including event properties (most receivers add properties to the received events to facilitate this routing)
- Tabs can be generated dynamically (similar to a database 'view') - 'view, create tab from expression' menu
- Right-click on a tab to hide or show tabs
- To the right of the tab's table is an area where search matches and color rule matches are visually displayed for the entire set of events (see the screenshots for an example)
- Event table
- Right-click in the table to configure the display, search, filter or define colors
- Click in the 'marker' field to annotate the log (saving the log via the File menu saves off the currently displayed events and preserves these annotations, so the events can be reloaded later, possibly by someone else)
- One handy display option which will wrap the message field to multiple lines in the table (no need for details pane): right-click in the table, select 'tab preferences, formatting, display entire message and marker text'
- Logger tree (can be hidden)
- As events are received, the event's logger is added to the logger tree
- Right-click on a logger node to hide or show the logger (and children), build a search expression or build a filter expression
- Detail pane (can be hidden)
- When a row is selected, the details of the event are displayed in the detail pane
- Select text in details and right-click to add to a search expression or filter expression
- User-configurable HTML details and a few pre-defined layouts - right click in the detail pane or click the 'drawing' icon
- Receivers pane
- The configuration used to process events is displayed in the 'receivers' pane, and can be modified from the UI. If receiver settings are modified in the UI, the original configuration file is not modified, but a file is created in $USER_HOME/.chainsaw called receiver-configs.xml, and Chainsaw can be configured to use this configuration automatically when Chainsaw is started
Common Chainsaw Commands
The 'Welcome' tab provides a list of popular commands and their shortcuts (F1 key toggles the display and hiding of the Welcome tab). Also, select Help-> Tutorial from the main menu.
Filter messages
There are three ways to filter events in Chainsaw
- Hide loggers - right click on loggers in the logger tree or left click and select the magnifying glass icons (persisted when Chainsaw is closed, on a per-tab basis)
- Ignore expression - a (possibly compound) expression which defines events that are not displayed in the table (persisted when Chainsaw is closed, on a per-tab basis)
- Refine focus field - enter an expression and events are dynamically filtered, or click down-arrow to reuse a previously entered expression (expressions are persisted when Chainsaw is closed, on a per-tab basis)
Filter by Logger
You may wish to see only the messages from the application logger, for example, to ensure the application is starting as expected. To filter out all messages except those from the application logger
1. Expand the Root Logger in the Logger pane 2. Highlight "application" logger 3. Click on the magnifying glass icon located just above the logger pane 4. Only the messages from this logger are displayed. To undo, click on the magnifying glass icon again.
Filter by severity
Sometimes all you want to see is the bad news - messages from any logger but with a severity level of WARN or worse.
1. Enter a filter expression in the box at the top of the Event pane. It is labeled, "Refine focus on: 2. LEVEL >= WARN 3. Only the messages matching the filter are displayed
Note: A simple expression-building mechanism is available anywhere you can enter an expression (search, filter and color expression definition) by right-clicking or pressing ctrl-space
Search for messages
Search expressions entered in the search field will cause any event matches to be colorized with the default search match color (configurable from the color settings dialog). If the tab preference for displaying search matches in the table is selected, search expression matches will be highlighted in the table. Also, search matches appear in the thumbnail bar/gutter as half-width black bars. To remove search highlighting, clear the search field and press enter (or F3).
Logger tree
From the logger tree, nodes can be hidden, added to filter or search expressions, or 'focused on'. 'Focus on' allows you to click on a logger node and only see events for that node and children - clicking on a different node displays only events for the newly-selected node and children. Clicking on a logger node without the 'focus on' field selected will cause events for that node and children to appear in the table with the search match color (an easy way to spot events for a certain logger without having to build a color rule).
Analyzing messages while debugging
Annotating messages
Click in the LOG4JMARKER column (located between TIMESTAMP and LEVEL on the Events pane) and type in your comment, such as, "Remember this!".
Show times as relative to the beginning of the run
Right-click on a row and select 'show times relative to this event', can be set again relative to a different event, or reset to display regular timestamps via the right-click context menu.
Preferences
Tail messages at the bottom
Press Ctrl-B or select the icon on the toolbar that looks like a table with an arrow pointing on the bottom row.
Clear all events from the Events pane
1. Press Ctrll-Backspace or select the trashcan icon, located in the menu bar, next to the "Search:" input box. 2. To reload events from RILog.txt after clearing the table, View -> Receivers, then click on the Receiver for the log, and press the 'half-round arrow icon' whose tooltip says 'Restarts the selected receiver'
Screen shots
Initial 'select a configuration' screen
Welcome screen (providing shortcuts, tutorial, example configuration)
Example receiver configuration (available from Welcome tab)
Tutorial screen (available from Welcome tab and help menu)
Multi-line mode (entire message field is wrapped in the table) - notice logger tree with ability to focus-on loggers in the tree and hide loggers
'Ignore expressions' dialog (hide rows containing benign warnings and errors - notice search match highlighted in table, thumbnail bar/gutter to the right of the table, search matches display as black half-wide bars in the gutter)
Context menu (define colors, configure tab-specific settings)
Single-line mode (message is truncated - notice 'detail' pane at the bottom with configurable HTML-formatted event details)
'Refine focus' (event filter) expression dialog - persists all expressions
Color settings panel (ordered color rules - also displayed in the thumbnail bar/gutter to the right of the table)
