[logback-dev] svn commit: r1460 - in logback/trunk/logback-site/src/site: pages resources/images/plugin
noreply.seb at qos.ch
noreply.seb at qos.ch
Mon Mar 26 21:26:31 CEST 2007
Author: seb
Date: Mon Mar 26 21:26:30 2007
New Revision: 1460
Added:
logback/trunk/logback-site/src/site/pages/consolePlugin.html
logback/trunk/logback-site/src/site/resources/images/plugin/
logback/trunk/logback-site/src/site/resources/images/plugin/buttons.gif (contents, props changed)
logback/trunk/logback-site/src/site/resources/images/plugin/createFilter.gif (contents, props changed)
logback/trunk/logback-site/src/site/resources/images/plugin/filterWindow.gif (contents, props changed)
logback/trunk/logback-site/src/site/resources/images/plugin/prefs.gif (contents, props changed)
logback/trunk/logback-site/src/site/resources/images/plugin/sampleLogs.gif (contents, props changed)
logback/trunk/logback-site/src/site/resources/images/plugin/stackTrace.gif (contents, props changed)
Log:
On going work on the plugin documentation
Added: logback/trunk/logback-site/src/site/pages/consolePlugin.html
==============================================================================
--- (empty file)
+++ logback/trunk/logback-site/src/site/pages/consolePlugin.html Mon Mar 26 21:26:30 2007
@@ -0,0 +1,299 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+<title>Logback Console Plugin for Eclipse</title>
+<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+<link rel="stylesheet" type="text/css" media="print" href="css/print.css" />
+
+</head>
+<body>
+ <script>
+prefix='';
+</script>
+
+<script src="templates/header.js"></script>
+<div id="left">
+ <script src="templates/left.js"></script>
+</div>
+<div id="right">
+ <script src="templates/right.js"></script>
+</div>
+<div id="content">
+
+ <h2>Logback Console Plugin for Eclipse</h2>
+
+ <p>
+ When developping a product, it is often useful to print logs to the console. Logging requests
+ are displayed using a <code>PatternLayout</code>, and one can easily see what happens when the
+ product runs.
+ </p>
+
+ <p>
+ The logback Console Plugin for Eclipse serves the same purpose, but offers several possibilities
+ that are not possible by using a simple output to the console. In short, here
+ are the key advantages of the logback plugin:
+ </p>
+
+ <ul>
+ <li>
+ Filter logs using logback's powerful filtering mechanism without changing
+ your logging configuration
+ </li>
+ <li>
+ View stacktraces in Eclipse's own StackTrace Console effortlessly
+ </li>
+ <li>
+ Immediately see where a certain logging request was issued
+ </li>
+ <li>
+ Easy configuration (only one line in your <em>logback.xml</em> file)
+ </li>
+ </ul>
+
+ <h3>Installation</h3>
+
+ <p>
+ Installing the plugin requires few steps. First get the plugin from
+ our <a href="download.html">download page</a>.
+ </p>
+
+ <p>
+ Once the transfert is complete, unzip the file called
+ <code>ch.qos.logback.eclipse_<em>VERSION</em>.zip</code>. Place the folder
+ found inside the archive in the following directory: <em>ECLIPSE_INSTALL/plugins/</em>
+ where <em>ECLIPSE_INSTALL</em> is the directory where you've installed Eclipse.
+ </p>
+
+ <p>
+ Relaunching Eclipse should do the trick. To access the logback plugin, open
+ the following menu: <em>Window > Show view > Other... </em>. You should see
+ the <em>Logback View</em> nested in the <em>Logback</em> category. Selecting the
+ view will add it to your workspace.
+ </p>
+
+ <h3>Logging to the logback plugin</h3>
+
+ <p>
+ Logging to the logback plugin takes a single line of configuration
+ in your <em>logback.xml</em> configuration file, as you can see below.
+ </p>
+
+ <div class="source"><pre><?xml version="1.0" encoding="UTF-8"?>
+
+<configuration>
+
+ <consolePlugin />
+
+</configuration></pre></div>
+
+ <p>
+ This element will trigger the creation of a <code>SocketAppender</code> that will send
+ events to the localhost, on port <em>4321</em> by default. That's all it takes to run your
+ software and log to the logback plugin.
+ </p>
+
+ <p>If you already have
+ a server running on the default port, you can specify the port that will be used
+ by adding a simple attribute to the xml element:
+ </p>
+
+ <div class="source"><pre><?xml version="1.0" encoding="UTF-8"?>
+
+<configuration>
+
+ <consolePlugin port="4567" />
+
+</configuration></pre></div>
+
+ <p>
+ In that case, however, you will need to specify in the plugin preferences on which
+ port to listen for events. The plugin preferences will be covered in the next section
+ of this document.
+ </p>
+
+ <h3>Using the logback plugin</h3>
+
+ <p>
+ Once the <em>Logback View</em> is shown on your workspace, you might want to
+ configure it to fit your needs. Look at the right side of the plugin view.
+ You should see two buttons, along with the usual three Eclipse icons:
+ </p>
+
+ <img src="images/plugin/buttons.gif" />
+
+ <p>
+ The first button on the left clears the console. The second button toggles
+ the auto-scroll functionnality. When enabled, you will always see the latest
+ logs that have been recieved by the plugin. If you disable the auto scrolling,
+ the view will display the current logs, and add the new ones at the bottom of
+ the list.
+ </p>
+
+ <p>
+ The third button opens a sub-menu that lets you configure the logback plugin.
+ </p>
+
+ <p>
+ When your software logs events, they are displayed in the logback view as shown
+ below:
+ </p>
+
+ <img src="images/plugin/sampleLogs.gif" />
+
+ <p>
+ All events with a level equal or higher to <em>WARN</em> are displayed in red.
+ </p>
+
+ <p>
+ Double-clicking on a log entry will open a Java editor and show you the line
+ where the entry was requested. It is an easy way to be access directly
+ to the class and method that logged the selected entry.
+ </p>
+
+ <p>
+ When an icon is shown on the left of the logging event, it means that the
+ logging event contains a stacktrace. Right-clicking on the line reveals
+ a sub-menu that lets you open Eclipse's StackTrace Console and display the
+ stacktrace.
+ </p>
+
+ <img src="images/plugin/stackTrace.gif" />
+
+ <h3>Configuring the logback plugin</h3>
+
+ <p>
+ On the right of the view, right next to the auto-scroll toggle is
+ a button that opens a sub menu.
+ </p>
+
+ <h4>Preferences</h4>
+
+ <p>
+ The first item in this menu opens the plugin's preference window.
+ </p>
+
+ <img src="images/plugin/prefs.gif" />
+
+ <p>
+ In this window, you can configure the pattern that will be used by the plugin
+ to display the logs. By default, it is configured to show the following informations:
+ </p>
+
+ <ul>
+ <li>
+ Relative time since launch
+ </li>
+ <li>
+ Level of the request
+ </li>
+ <li>
+ The thread name
+ </li>
+ <li>
+ Name of the logger. The name is automatically shortened when longer than
+ 25 characters
+ </li>
+ <li>
+ The message of the request
+ </li>
+ </ul>
+
+ <p>
+ An important point about this pattern is that, if it is modified, the changes
+ are immediately reflected on the <strong>current content</strong> of the logback view.
+ That means that if you would like to display an <code>MDC</code> value, or any other
+ information that the <code>PatternLayout</code> provides, you can change it even
+ <em>after</em> the logs have been requested.
+ </p>
+
+ <p>
+ Along with the pattern, you can specify the port on which the plugin will listen
+ for logging events. You can also choose the font type and size that will be used
+ to display the logs in the logback view.
+ </p>
+
+
+ <h4>Filters</h4>
+
+ <p>
+ The logback plugin lets you filter logging events when they are
+ recieved. It uses the powerfull <code>EvaluatorFilter</code>objects
+ that are available in logback. For detailled information about these filters, you might want
+ to check the <a href="manual/filters.html">corresponding documentation</a>
+ in the logback manual. In this document, we will only
+ cover some basic points, enough to get you started using the filtering
+ functionnality of the logback plugin.
+ </p>
+
+ <p>
+ The second item of the sub-menu on the right of the logback view
+ opens the filter configuration window:
+ </p>
+
+ <img src="images/plugin/filterWindow.gif" />
+
+ <p>
+ The upper part of the window lists the filters that are currently
+ used by the logback plugin. The lower part lets you create, edit
+ or delete a filter.
+ </p>
+
+ <p>
+ A filter is composed of three informations. First, a Java expression,
+ that will be evaluated for each logging event that is recieved by
+ the logback plugin. This expression can use a set of common variables
+ such as <code>level</code>, <code>logger</code>, <code>message</code>,
+ and several others. For a complete list of available variables, please
+ refer to the <a href="manual/filters#EventEvaluator.html">chapter
+ about filters</a> in the logback manual.
+ </p>
+
+ <p>
+ The second and third informations that compose a filter are the
+ action that will be taken when the evaluated expression is satisfied
+ or not. Three actions are possible: <em>ACCEPT</em>, <em>DENY</em>
+ or <em>NEUTRAL</em>. Setting a filter's reply to <em>ACCEPT</em>
+ or <em>DENY</em> will prevent the plugin from evaluating any
+ other filter and return a definitive result on the logging event.
+ </p>
+
+ <p>
+ Let us create a filter that will drop any request that has a level
+ lower than <em>INFO</em>. A click on the <em>New</em> button creates
+ a new filter. Enter the following informations in the corresponding
+ fields:
+ </p>
+
+ <ul>
+ <li>
+ Expression: <code>level &ght;= INFO</code>
+ </li>
+ <li>
+ Action on filter match: <code>NEUTRAL</code>
+ </li>
+ <li>
+ Action on filter mismatch: <code>DENY</code>
+ </li>
+ </ul>
+
+ <p>
+ Here is what the window should look like, once you've
+ saved the filter.
+ </p>
+
+ <img src="images/plugin/createFilter.gif" />
+
+ <p>
+ We've just created a filter that will drop any requests whose
+ level is lower than <em>INFO</em>. Note the use of the <em>NEUTRAL</em>
+ value as the action to be taken when the filter is matched. Since
+ we do not know what other filters might want to do, there is not reason
+ to stop evaluating when the level is higher or equal to <em>INFO</em>.
+ </p>
+
+
+<script src="templates/footer.js"></script>
+</div>
+</body>
+</html>
Added: logback/trunk/logback-site/src/site/resources/images/plugin/buttons.gif
==============================================================================
Binary file. No diff available.
Added: logback/trunk/logback-site/src/site/resources/images/plugin/createFilter.gif
==============================================================================
Binary file. No diff available.
Added: logback/trunk/logback-site/src/site/resources/images/plugin/filterWindow.gif
==============================================================================
Binary file. No diff available.
Added: logback/trunk/logback-site/src/site/resources/images/plugin/prefs.gif
==============================================================================
Binary file. No diff available.
Added: logback/trunk/logback-site/src/site/resources/images/plugin/sampleLogs.gif
==============================================================================
Binary file. No diff available.
Added: logback/trunk/logback-site/src/site/resources/images/plugin/stackTrace.gif
==============================================================================
Binary file. No diff available.
More information about the logback-dev
mailing list