src/java/org/apache/log4j/chainsaw/help/tutorial.html - logging-chainsaw - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <HTML>
 <HEAD>
 <link rel="stylesheet" href="../stylesheet.css" type="text/css">
 </HEAD>

 <BODY>
 <p>Welcome to the Chainsaw v2 Tutorial.  Here you will learn how to effectively utilise the many features of Chainsaw.</p>
 </p>
 <p><a href="#expressions">Expressions</a>
 <p><a href="#color_filter">Color filters</a>
 <p><a href="#display_filter">Display filters</a>
 <h2>Conventions</h2>
 <p>To assist you, the following documentation conventions will be used</p>
 <ul>
 <li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">Interesting items will be shown like this</li>
 <li><img src="../icons/Help16.gif" alt="Try this...">Things you should try during the tutorial will be shown like this</li>
 </ul>
 </p>
 <h2>Outline</h2>
 <p>The built-in tutorial installs several "pretend" Receiver plugins that generate some example LoggingEvents and post
 them into Log4j just like a real Receiver.  </p>
 <ul>
 <li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">If you would like to read more about Receivers first, then click here. <font color="red"><b>(TODO)</b></font></li>
 </ul>
 <hr>
 <p><b>When you are ready to begin the tutorial, <a href="StartTutorial">click here</a>, or click the "Start Tutorial" button in this dialog's toolbar.</b></p>
 <hr>
 <h2>Receivers</h2>
 <p>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.
 </p>
 <ul>
 <li><img src="../icons/Help16.gif" alt="Try this...">Confirm
 this by showing the Receivers panel accessible either via the toolbar or the menu. The icon for this action is <img src="../icons/channelexplorer_satellite.gif"></li>
 </ul>
 <p>
 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.
 <ul>
 <li><img src="../icons/Help16.gif" alt="Try this...">Try right clicking on a specific receiver and looking at the available menu options, but don't change anything just yet.</li>
 <li><img src="../icons/Help16.gif" alt="Try this...">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.</li>
 </ul>
 </p>
 <h2>Tabs</h2>
 <p>
 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.  <font color="red"><b>TODO</b></font>
 </p>
 <ul>
 <li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">You may also notice that the tabs have the receiver icon (<img src="../icons/channelexplorer_satellite.gif">).  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 <img src="../icons/Information16.gif"> icon is shown.</li>
 </ul>
 <ul>
 <li><img src="../icons/Help16.gif" alt="Try this...">Click on each tab and see how the icons shown in the tabs change.</li>
 <li><img src="../icons/Help16.gif" alt="Try this...">When you click on a specific tab, you should notice the events are streaming in.</li>
 </ul>
 <h2>Log Tabs</h2>
 <p>Each tab contains a series of LoggingEvents routed to it via the Chainsaw internals. This visual panel
 is known as the <b>Log Panel</b>. It contains 3 main areas:
 <ol>
 <li><b>Events panel</b> - The top/central panel contains a table of all the events received, and the Refinement filter (more on this later)</li>
 <li><b>Event Detail panel</b> - The bottom/central panel contains more details information of the currently selected event in the table.</li>
 <li><b>Logger Tree panel</b> - the left hand panel contains all the distinct loggers known from the
 received LoggingEvents represented in the natural dotted hierarchy.</li>
 </ol>
 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.
 <ul>
 <li><img src="../icons/Help16.gif" alt="Try this...">Try hiding/showing/resizing the Logger Tree and Event Detail panels to see how they affect your viewing area.
 </ul>
 </p>
 <h3>Events panel</h3>
 <p>
 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.</p>
 <p>Each of the columns can be moved and resized.  When you exit, Chainsaw will remember these settings automatically.</p>
 <ul>
 <li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">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.</li>
 <li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">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.</li>
 <li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">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</li>
 <li><img src="../icons/Help16.gif" alt="Try this...">Try viewing the stack trace detail by clicking on a Throwable cell, and clicking the "..." button.</li>

 </ul>
 <p>
 The popup menu on this panel contains some handy features:
 <ul>
 <li>Scroll to Bottom - follows the new events as the arrive (sort of like the 'tail' command)</li>
 <li>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.</li>
 </ul>
 </p>
 <h3>Event Detail panel</h3>
 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.
 <ul>
 <li><img src="../icons/Help16.gif" alt="Try this...">Try right clicking on the contents of the Event Detail panel and switching between the various Layouts included.</li>
 <li><img src="../icons/Help16.gif" alt="Try this...">Try clicking on the <img src="../icons/Edit16.gif"> icon in the Event Detail toolbar, or popup menu to show the Layout Pattern editor, and edit it to see how changes are reflected.</li>
 </ul>

 <h3>Logger Tree panel</h3>
 <font color="red"><b>TODO</b></font>
 <p>

 <A NAME="expressions"><h3>Expressions</h3>
 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.

 <ul>
 <li>Precedence can be controlled by applying parentheses to groups of expressions (usually used in combination with logical operators)</li>
 <li>All operators, operands and parentheses must be separated by spaces</li>
 <li>Single tick marks can be used to delimit multi-word operands</li>
 <li>Example: msg ~= <b>'my msg'</b></li>
 <li><b>NOTE:</b> A context menu is available anywhere you can enter an expression in order to assist in constructing expressions (use the right-mouse click or ctrl-space to activate the context menu) </li>
 </ul>

 <b>Define an expression:</b>
 <ol>
 <li>Select the field identifier (a keyword representing a logging event field) required to perform the evaluation.  <b>Field identifiers are not case sensitive.  </b>See the list of supported field identifiers below</li>
 <li>Example: use the <B>MSG</B> field identifier in an expression to evaluate the 'message' field of the logging event</li>
 <li>Select the operator needed to perform the evaluation.  See the list of supported operators below.</li>
 <li>
 Example: to perform a case-insensitive partial-text evaluation, use the <b>~=</b> operator</li>
 <li>Define the value to be matched in the expression (required by all operators except logical operators).</li>
 <li>
 Example: to display only events which are greater than or equal to level INFO, use the expression <b>LEVEL >= INFO</b></li>
 </ol>

 <ul>
 <li>The field identifier/operator/operand combination itself is a valid expression, but can be used in combination with other expressions and logical operators (&&, ||) in order to define complex expressions</li>
 <li>Modify the precedence of expressions in a complex expression by surrounding the expression(s) in parentheses</li>
 </ul>

 <b>Supported field identifiers:</b>
 <ul>
 <li>LOGGER</li>
 <li>LEVEL</li>
 <li>CLASS</li>
 <li>FILE</li>
 <li>LINE</li>
 <li>METHOD</li>
 <li>MSG</li>
 <li>NDC</li>
 <li>EXCEPTION</li>
 <li>TIMESTAMP</li>
 <li>THREAD</li>
 <li>PROP.[key name]</li>
 </ul>

 <ul>
 <li><b>NOTE: </b>To build expressions using <b>PROP (properties)</b> field identifier, the key being evaluated must be added after the field identifier and a period</li>
  <li>Example: all events in the event table contain a '<b>log4jid</b>' property (used during import/export of events).  To refine the display to display only rows 50 through 60, the expression <b>PROP.log4jid &gt= 50 && PROP.log4jid &lt= 60</b> can be used in the 'refine focus' field</li>
 <b>NOTE:</b> PROP keys are case sensitive.  <b>PROP.log4jid</b> is <b>not</b> equivalent to <b>PROP.LOG4JID</b>
 </ul>
 <p>
 <b>Supported operators:</b></p>
 <table border=1>
 <th>Symbol</th><th>Description</th>
 <tr><td align="center">==</td><td>equals</td></tr>
 <tr><td align="center">~=</td><td>case-insensitive partial-text match</td></tr>
 <tr><td align="center">!=</td><td>not equals</td></tr>
 <tr><td align="center">LIKE</td><td>supports regular expressions</td></tr>
 <tr><td align="center">EXISTS</td><td>not null</td></tr>
 <tr><td align="center">&lt</td><td rowspan="4">inequality operators</td></tr>
 <tr><td align="center">&lt=</td></tr>
 <tr><td align="center">&gt</td></tr>
 <tr><td align="center">&gt=</td></tr>
 <tr><td align="center">&&</td><td>logical and</td></tr>
 <tr><td align="center">||</td><td>logical or</td></tr>
 <tr><td align="center">!</td><td>logical not</td></tr>
 </table>

 <p><b>Expression shortcut:</b></p>
 <ul>
 <li>Since it is very common need to perform a case-insensitive partial-text match against the Message field, any single word or any single phrase (the phrase must be delimited by single-quote marks) will act as a rule defined using the MSG ~= syntax.</li>
 <li>Example: to search the Message field for the phrase 'logged in', instead of defining the expression <b>MSG ~= 'logged in'</b>, use <b>'logged in'</b> by itself (including the single quotes).  Instead of using <b>MSG ~= evaluation</b> to search for the word 'evaluation', use <b>evaluation</b> by itself (no need for single quotes since it's a single word).</li>
 <li><b>NOTE:</b> This shortcut syntax is designed to be used to search for <b>single words or phrases only</b>, and will not work when used in combination with other operators or expressions.  When building complex expressions, use the <B>MSG ~=</B> syntax.</li>
 </ul>

 <p><b>Operator limitations:</b></p>
 <ul>
 <li>Inequality operators are supported for Levels (<b>LEVEL &gt info</b>) and anything that can be converted to a numeric value (including timestamps).</li>
 <li>In order to build expressions using the Timestamp field, provide the Timestamp value in this format: 'yyyy/MM/dd HH:mm:ss'.  Note the single ticks, which are required because of the space between the days and hours. The Timestamp field contains millisecond information, but the milliseconds are rounded off during event evaluation.</li>
 </ul>

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

 <A NAME="color_filter"><h3>Color filters</h3>
 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.

 <p><b>Define color rules:</b></p>
 <ol>
 <li>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'</li>
 <li>Select 'new' to add a row</li>
 <li>Double-click on the 'expression' column</li>
 <li>Enter an expression (see <a href="#expressions">Expressions</a>)</li>
 <li>Select a color from the list or use the 'browse' button at the bottom of the color list to define a custom color</li>
 <li>Repeat steps 2 - 5 as needed</li>
 <li>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</li>
 <li>Apply the rules.  The event panel will be updated based on the defined color rules</li>
 <li>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</li>
 <li>Fix errors as needed, apply and close the panel</li>
 </ol>

 <A NAME="display_filter"><h3>Display filters (refine focus)</h3>
 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.
 <p>
 <b>NOTE:</b>Display filter rules are not saved.

 <p>
 <b>Define display rules:</b></p>
 <ol>
 <li>Move the cursor to the 'refine focus on' field</li>
 <li>Enter an expression (see <a href="#expressions">Expressions</a>)</li>
 <li>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 <b>set 'refine focus' field</b> will assign the expression <b>THREAD == 'Thread-1'</b> to the refine focus field.</li>
 <li>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</li>
 <li>If the expression entered is invalid, an error message will available as the 'refine focus on' field's tooltip</li>
 <li>If the <b>ENTER</b> 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</li>
 </ol>

 <h2>Shutting down the Tutorial</h2>
 <p>
 When you are finished with the tutorial, you can simply shutdown all the Generator receivers:
 <ul>
 <li><img src="../icons/Help16.gif" alt="Try this...">Show the Receivers panel () and shutdown each of the Generator Receivers by using the <img src="../icons/Stop16.gif" alt="Stop"> icon.</li>
 </ul>
 <p>For convenience you can simply <a href="StopTutorial">click here</a> 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).</p>
 </p>
 <hr>
 <PRE>Transmission Ends</PRE>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<HTML>
	<HEAD>
	<link rel="stylesheet" href="../stylesheet.css" type="text/css">
	</HEAD>

	<BODY>
	<p>Welcome to the Chainsaw v2 Tutorial. Here you will learn how to effectively utilise the many features of Chainsaw.</p>
	</p>
	<p><a href="#expressions">Expressions</a>
	<p><a href="#color_filter">Color filters</a>
	<p><a href="#display_filter">Display filters</a>
	<h2>Conventions</h2>
	<p>To assist you, the following documentation conventions will be used</p>
	<ul>
	<li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">Interesting items will be shown like this</li>
	<li><img src="../icons/Help16.gif" alt="Try this...">Things you should try during the tutorial will be shown like this</li>
	</ul>
	</p>
	<h2>Outline</h2>
	<p>The built-in tutorial installs several "pretend" Receiver plugins that generate some example LoggingEvents and post
	them into Log4j just like a real Receiver. </p>
	<ul>
	<li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">If you would like to read more about Receivers first, then click here. <font color="red"><b>(TODO)</b></font></li>
	</ul>
	<hr>
	<p><b>When you are ready to begin the tutorial, <a href="StartTutorial">click here</a>, or click the "Start Tutorial" button in this dialog's toolbar.</b></p>
	<hr>
	<h2>Receivers</h2>
	<p>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.
	</p>
	<ul>
	<li><img src="../icons/Help16.gif" alt="Try this...">Confirm
	this by showing the Receivers panel accessible either via the toolbar or the menu. The icon for this action is <img src="../icons/channelexplorer_satellite.gif"></li>
	</ul>
	<p>
	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.
	<ul>
	<li><img src="../icons/Help16.gif" alt="Try this...">Try right clicking on a specific receiver and looking at the available menu options, but don't change anything just yet.</li>
	<li><img src="../icons/Help16.gif" alt="Try this...">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.</li>
	</ul>
	</p>
	<h2>Tabs</h2>
	<p>
	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. <font color="red"><b>TODO</b></font>
	</p>
	<ul>
	<li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">You may also notice that the tabs have the receiver icon (<img src="../icons/channelexplorer_satellite.gif">). 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 <img src="../icons/Information16.gif"> icon is shown.</li>
	</ul>
	<ul>
	<li><img src="../icons/Help16.gif" alt="Try this...">Click on each tab and see how the icons shown in the tabs change.</li>
	<li><img src="../icons/Help16.gif" alt="Try this...">When you click on a specific tab, you should notice the events are streaming in.</li>
	</ul>
	<h2>Log Tabs</h2>
	<p>Each tab contains a series of LoggingEvents routed to it via the Chainsaw internals. This visual panel
	is known as the <b>Log Panel</b>. It contains 3 main areas:
	<ol>
	<li><b>Events panel</b> - The top/central panel contains a table of all the events received, and the Refinement filter (more on this later)</li>
	<li><b>Event Detail panel</b> - The bottom/central panel contains more details information of the currently selected event in the table.</li>
	<li><b>Logger Tree panel</b> - the left hand panel contains all the distinct loggers known from the
	received LoggingEvents represented in the natural dotted hierarchy.</li>
	</ol>
	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.
	<ul>
	<li><img src="../icons/Help16.gif" alt="Try this...">Try hiding/showing/resizing the Logger Tree and Event Detail panels to see how they affect your viewing area.
	</ul>
	</p>
	<h3>Events panel</h3>
	<p>
	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.</p>
	<p>Each of the columns can be moved and resized. When you exit, Chainsaw will remember these settings automatically.</p>
	<ul>
	<li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">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.</li>
	<li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">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.</li>
	<li><img src="../icons/TipOfTheDay16.gif" alt="Interesting...">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</li>
	<li><img src="../icons/Help16.gif" alt="Try this...">Try viewing the stack trace detail by clicking on a Throwable cell, and clicking the "..." button.</li>

	</ul>
	<p>
	The popup menu on this panel contains some handy features:
	<ul>
	<li>Scroll to Bottom - follows the new events as the arrive (sort of like the 'tail' command)</li>
	<li>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.</li>
	</ul>
	</p>
	<h3>Event Detail panel</h3>
	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.
	<ul>
	<li><img src="../icons/Help16.gif" alt="Try this...">Try right clicking on the contents of the Event Detail panel and switching between the various Layouts included.</li>
	<li><img src="../icons/Help16.gif" alt="Try this...">Try clicking on the <img src="../icons/Edit16.gif"> icon in the Event Detail toolbar, or popup menu to show the Layout Pattern editor, and edit it to see how changes are reflected.</li>
	</ul>

	<h3>Logger Tree panel</h3>
	<font color="red"><b>TODO</b></font>
	<p>

	<A NAME="expressions"><h3>Expressions</h3>
	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.

	<ul>
	<li>Precedence can be controlled by applying parentheses to groups of expressions (usually used in combination with logical operators)</li>
	<li>All operators, operands and parentheses must be separated by spaces</li>
	<li>Single tick marks can be used to delimit multi-word operands</li>
	<li>Example: msg ~= <b>'my msg'</b></li>
	<li><b>NOTE:</b> A context menu is available anywhere you can enter an expression in order to assist in constructing expressions (use the right-mouse click or ctrl-space to activate the context menu) </li>
	</ul>

	<b>Define an expression:</b>
	<ol>
	<li>Select the field identifier (a keyword representing a logging event field) required to perform the evaluation. <b>Field identifiers are not case sensitive. </b>See the list of supported field identifiers below</li>
	<li>Example: use the <B>MSG</B> field identifier in an expression to evaluate the 'message' field of the logging event</li>
	<li>Select the operator needed to perform the evaluation. See the list of supported operators below.</li>
	<li>
	Example: to perform a case-insensitive partial-text evaluation, use the <b>~=</b> operator</li>
	<li>Define the value to be matched in the expression (required by all operators except logical operators).</li>
	<li>
	Example: to display only events which are greater than or equal to level INFO, use the expression <b>LEVEL >= INFO</b></li>
	</ol>

	<ul>
	<li>The field identifier/operator/operand combination itself is a valid expression, but can be used in combination with other expressions and logical operators (&&, \|\|) in order to define complex expressions</li>
	<li>Modify the precedence of expressions in a complex expression by surrounding the expression(s) in parentheses</li>
	</ul>

	<b>Supported field identifiers:</b>
	<ul>
	<li>LOGGER</li>
	<li>LEVEL</li>
	<li>CLASS</li>
	<li>FILE</li>
	<li>LINE</li>
	<li>METHOD</li>
	<li>MSG</li>
	<li>NDC</li>
	<li>EXCEPTION</li>
	<li>TIMESTAMP</li>
	<li>THREAD</li>
	<li>PROP.[key name]</li>
	</ul>

	<ul>
	<li><b>NOTE: </b>To build expressions using <b>PROP (properties)</b> field identifier, the key being evaluated must be added after the field identifier and a period</li>
	<li>Example: all events in the event table contain a '<b>log4jid</b>' property (used during import/export of events). To refine the display to display only rows 50 through 60, the expression <b>PROP.log4jid &gt= 50 && PROP.log4jid &lt= 60</b> can be used in the 'refine focus' field</li>
	<b>NOTE:</b> PROP keys are case sensitive. <b>PROP.log4jid</b> is <b>not</b> equivalent to <b>PROP.LOG4JID</b>
	</ul>
	<p>
	<b>Supported operators:</b></p>
	<table border=1>
	<th>Symbol</th><th>Description</th>
	<tr><td align="center">==</td><td>equals</td></tr>
	<tr><td align="center">~=</td><td>case-insensitive partial-text match</td></tr>
	<tr><td align="center">!=</td><td>not equals</td></tr>
	<tr><td align="center">LIKE</td><td>supports regular expressions</td></tr>
	<tr><td align="center">EXISTS</td><td>not null</td></tr>
	<tr><td align="center">&lt</td><td rowspan="4">inequality operators</td></tr>
	<tr><td align="center">&lt=</td></tr>
	<tr><td align="center">&gt</td></tr>
	<tr><td align="center">&gt=</td></tr>
	<tr><td align="center">&&</td><td>logical and</td></tr>
	<tr><td align="center">\|\|</td><td>logical or</td></tr>
	<tr><td align="center">!</td><td>logical not</td></tr>
	</table>

	<p><b>Expression shortcut:</b></p>
	<ul>
	<li>Since it is very common need to perform a case-insensitive partial-text match against the Message field, any single word or any single phrase (the phrase must be delimited by single-quote marks) will act as a rule defined using the MSG ~= syntax.</li>
	<li>Example: to search the Message field for the phrase 'logged in', instead of defining the expression <b>MSG ~= 'logged in'</b>, use <b>'logged in'</b> by itself (including the single quotes). Instead of using <b>MSG ~= evaluation</b> to search for the word 'evaluation', use <b>evaluation</b> by itself (no need for single quotes since it's a single word).</li>
	<li><b>NOTE:</b> This shortcut syntax is designed to be used to search for <b>single words or phrases only</b>, and will not work when used in combination with other operators or expressions. When building complex expressions, use the <B>MSG ~=</B> syntax.</li>
	</ul>

	<p><b>Operator limitations:</b></p>
	<ul>
	<li>Inequality operators are supported for Levels (<b>LEVEL &gt info</b>) and anything that can be converted to a numeric value (including timestamps).</li>
	<li>In order to build expressions using the Timestamp field, provide the Timestamp value in this format: 'yyyy/MM/dd HH:mm:ss'. Note the single ticks, which are required because of the space between the days and hours. The Timestamp field contains millisecond information, but the milliseconds are rounded off during event evaluation.</li>
	</ul>

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

	<A NAME="color_filter"><h3>Color filters</h3>
	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.

	<p><b>Define color rules:</b></p>
	<ol>
	<li>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'</li>
	<li>Select 'new' to add a row</li>
	<li>Double-click on the 'expression' column</li>
	<li>Enter an expression (see <a href="#expressions">Expressions</a>)</li>
	<li>Select a color from the list or use the 'browse' button at the bottom of the color list to define a custom color</li>
	<li>Repeat steps 2 - 5 as needed</li>
	<li>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</li>
	<li>Apply the rules. The event panel will be updated based on the defined color rules</li>
	<li>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</li>
	<li>Fix errors as needed, apply and close the panel</li>
	</ol>

	<A NAME="display_filter"><h3>Display filters (refine focus)</h3>
	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.
	<p>
	<b>NOTE:</b>Display filter rules are not saved.

	<p>
	<b>Define display rules:</b></p>
	<ol>
	<li>Move the cursor to the 'refine focus on' field</li>
	<li>Enter an expression (see <a href="#expressions">Expressions</a>)</li>
	<li>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 <b>set 'refine focus' field</b> will assign the expression <b>THREAD == 'Thread-1'</b> to the refine focus field.</li>
	<li>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</li>
	<li>If the expression entered is invalid, an error message will available as the 'refine focus on' field's tooltip</li>
	<li>If the <b>ENTER</b> 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</li>
	</ol>

	<h2>Shutting down the Tutorial</h2>
	<p>
	When you are finished with the tutorial, you can simply shutdown all the Generator receivers:
	<ul>
	<li><img src="../icons/Help16.gif" alt="Try this...">Show the Receivers panel () and shutdown each of the Generator Receivers by using the <img src="../icons/Stop16.gif" alt="Stop"> icon.</li>
	</ul>
	<p>For convenience you can simply <a href="StopTutorial">click here</a> 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).</p>
	</p>
	<hr>
	<PRE>Transmission Ends</PRE>
	</body>
	</html>