Welcome to the Chainsaw v2 Tutorial. Here you will learn how to effectively utilise the many features of Chainsaw.
Conventions
To assist you, the following documentation conventions will be used
Interesting items will be shown like this
Things you should try during the tutorial will be shown like this
Outline
The built-in tutorial installs several "pretend" Receiver plugins that generate some example LoggingEvents and post
them into Log4j just like a real Receiver.
If you would like to read more about Receivers first, then click here. (TODO)
When you are ready to begin the tutorial, click here, or click the "Start Tutorial" button in this dialog's toolbar.
Receivers
After you have said yes to the confirmation dialog, you should see 3 new tabs appear
in the main GUI. This is because the tutorial has installed 3 'Generator' Receivers into the Log4j engine.
Confirm
this by showing the Receivers panel accessible either via the toolbar or the menu. The icon for this action is 
Any installed receiver installed into Log4j, either via an external configuration file, or via the GUI, is shown in this panel. You
can create new Receivers, stop existing ones, or adjust their threshold.
Try right clicking on a specific receiver and looking at the available menu options, but don't change anything just yet.
When you are finished looking at the Receiver panel, hide it by clicking the 'X" close icon in the top right corner,
or toggling the Receivers panel by clicking the icon in the toolbar, or using the menu.
Tabs
You may have noticed that each of the tabs have specific names ("Generator X"). Chainsaw automatically looks inside
each received LoggingEvent for a special Application property to determine which tab to route an event to. If it cannot find
this property, it attempts to use a secondary property usually added via the SocketAppender or SocketHubAppender which
identify the remote host of these events. If neither of these are found, Chainsaw routes events to a default "Unknown" tab. You can learn more about
this whole process here. TODO
You may also notice that the tabs have the receiver icon (
). This is to indicate that new events are arriving for this tab. Additionally
if new events are not arriving, but there are events newer than the last time you looked at this tab, then the
icon is shown.
Click on each tab and see how the icons shown in the tabs change.
When you click on a specific tab, you should notice the events are streaming in.
Log Tabs
Each tab contains a series of LoggingEvents routed to it via the Chainsaw internals. This visual panel
is known as the Log Panel. It contains 3 main areas:
- Events panel - The top/central panel contains a table of all the events received, and the Refinement filter (more on this later)
- Event Detail panel - The bottom/central panel contains more details information of the currently selected event in the table.
- Logger Tree panel - the left hand panel contains all the distinct loggers known from the
received LoggingEvents represented in the natural dotted hierarchy.
The Logger Tree & Event Detail panels can be hidden by clicking on the 'X' close icon in their respective top left corners, or
by using the toolbar or menus. They are also contained within a split area, so you can adjust the amount
of visual space they take up to your liking.
Try hiding/showing/resizing the Logger Tree and Event Detail panels to see how they affect your viewing area.
Events panel
The Events panel primary role is to display received events in a table. Events are colored based
on certain rules, with a default set of rules coloring a row based on the LoggingEvent level: Red for ERROR, Yellow for WARN.
Each of the columns can be moved and resized. When you exit, Chainsaw will remember these settings automatically.
If you click on a column header, it will sort the viewable events by this column, and subsequent clicks will toggle between ascending and descending mode.
Notice that the Level column displays an iconic representation of the Level. You can switch between this and Text mode by using the View->Display Level column as menu.
The Throwable column shows only the first line of the stack trace, but if you click on a Throwable cell, you will notice a "..." button. Clicking this pops up a detailed view of the stack trace
Try viewing the stack trace detail by clicking on a Throwable cell, and clicking the "..." button.
The popup menu on this panel contains some handy features:
- Scroll to Bottom - follows the new events as the arrive (sort of like the 'tail' command)
- Show Tooltips - you can hover the mouse cursor over an event row and Chainsaw will show you that events contents within the tooltip. Handy for glancing at more details of events.
Event Detail panel
The Event Detail panel shows a more detailed view of the currently selected LoggingEvent from the Events panel. The format of the event information
is determined by the layout chosen. Internally Chainsaw uses Log4j's Layout classes, so if you are familiar with them, you'll feel right at home.
The default layout uses a PatternLayout with HTML formatting.
Try right clicking on the contents of the Event Detail panel and switching between the various Layouts included.
Try clicking on the
icon in the Event Detail toolbar, or popup menu to show the Layout Pattern editor, and edit it to see how changes are reflected.
Logger Tree panel
TODO
Filtering
TODO
Shutting down the Tutorial
When you are finished with the tutorial, you can simply shutdown all the Generator receivers:
Show the Receivers panel () and shutdown each of the Generator Receivers by using the
icon.
For convenience you can simply click here or click on the Stop Tutorial button in this dialogs toolbar, and Chainsaw will stop all the tutorial generators for you (If you created any other non-Generator Receivers, they will be left untouched).
Transmission Ends