Welcome to the Chainsaw v2 Tutorial. Here you will learn how to effectively utilise the many features of Chainsaw.

Expressions

Search

Display filters

Color filters

Conventions

To assist you, the following documentation conventions will be used

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.


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.

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.

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

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:

  1. Events panel - The top/central panel contains a table of all the events received, and the Refinement filter (more on this later)
  2. Event Detail panel - The bottom/central panel contains more details information of the currently selected event in the table.
  3. 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.

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.

The popup menu on this panel contains some handy features:

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.

Logger Tree panel

TODO

Expressions

Expressions are used to define color and display rules in Chainsaw. An expression is a textual representation of a rule, and provides the ability to perform queries against a collection of logging events. As each logging event is examined by the rule, the operation associated with the rule is performed providing the event passes the rule's evaluation. For example, the event may be assigned a color or added to the display. Log4J's rule expression syntax provides access to all of the logging event's fields, a number of operators, and the ability to control precedence. Define an expression:
  1. Select the field identifier (a keyword representing a logging event field) required to perform the evaluation. Field identifiers are not case sensitive. See the list of supported field identifiers below
  2. Example: use the MSG field identifier in an expression to evaluate the 'message' field of the logging event
  3. Select the operator needed to perform the evaluation. See the list of supported operators below.
  4. Example: to perform a case-insensitive partial-text evaluation, use the ~= operator
  5. Define the value to be matched in the expression (required by all operators except logical operators).
  6. Example: to display only events which are greater than or equal to level INFO, use the expression LEVEL >= INFO
Supported field identifiers:

Supported operators:

SymbolDescription
==equals
~=case-insensitive partial-text match
!=not equals
LIKEsupports regular expressions
EXISTSnot null
<inequality operators
<=
>
>=
&&logical and
||logical or
!logical not

Expression shortcut:

Operator limitations:

Example expressions:

To display all events with a level of info or greaterLEVEL >= INFO
To display all events which contain the words 'logged in' in the message MSG ~= 'logged in'
To display all events which contain an exceptionEXCEPTION EXISTS
To display all events associated with a PROP key of USERID with a value of 'tester'PROP.USERID == tester
'and' the first and second examples together, 'or'd with the third( LEVEL >= INFO && MSG ~= 'logged in' ) || EXCEPTION EXISTS
To display all events between 23:55 and 23:56 on the 19th of JuneTIMESTAMP >= '2004/06/19 23:55:00' && TIMESTAMP <= '2004/06/19 23:56:00'
To display events occurring at 23:55:12 on the 19th of June (all events generated during that second, regardless of millisecond value)TIMESTAMP == '2004/06/19 23:55:12'

Find

How to find:

Display filters (refine focus)

Events displayed in the event panel can be filtered in two ways: by focusing on a logger in the logger tree panel and by defining display filter rules in the 'refine focus' field.

NOTE:Display filter rules are saved.

Define display rules:

  1. Move the cursor to the 'refine focus on' field
  2. Enter an expression (see Expressions) (use the right-mouse click or ctrl-space to activate a context menu which can assist in constructing expressions)
  3. Alternatively, use the context (mouse right click) menu (available when the mouse pointer is over the events table) to modify the 'refine focus' field's expression based on the field and value under the mouse pointer. For example, if the mouse pointer is over the THREAD cell of an event which has a value of Thread-1, selecting set 'refine focus' field will assign the expression THREAD == 'Thread-1' to the refine focus field.
  4. The display will be updated automatically if the expression is valid and the contents of the 'refine focus' field have not changed for 1 second, showing only events which match the expression
  5. If the expression entered is invalid, an error message will available as the 'refine focus on' field's tooltip
  6. If the ENTER key is pressed when a valid expression is in the 'refine focus on' field, the expression is added to the refine focus drop down list and can be recalled later in the session

Color filters

Each log panel can define color rules which can be used to colorize events in the event panel. Color rules are associated with each event panel and are saved when the application ends and loaded automatically when the application starts.

Define color rules:

  1. Open the color filter panel by selecting the 'current tab, log panel color filter' menu items, or by using the context (right-click mouse) menu in the events panel and selecting 'log panel color filter'
  2. Select 'new' to add a row
  3. Double-click on the 'expression' column
  4. Enter an expression (see Expressions)
  5. Select a color from the list or use the 'browse' button at the bottom of the color list to define a custom color
  6. Repeat steps 2 - 5 as needed
  7. Order the rules - rules are evaluated in order. Select a color rule entry and press the UP or DOWN icons on the panel as needed
  8. Apply the rules. The event panel will be updated based on the defined color rules
  9. If there are invalid expressions, a message at the bottom will direct you to hover the mouse over an expression to see the error as the entry's tooltip
  10. Fix errors as needed, apply and close the panel

Shutting down the Tutorial

When you are finished with the tutorial, you can simply shutdown all the Generator receivers:

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