## Logback Console Plugin for Eclipse

During the development process, it is common for developers to print log output on the console. Typically, the developer will also customize the format of the log output by setting properties of a `PatternLayout` instance. The Logback Console Plugin for Eclipse serves the same purpose as the regular console, but offers several advantages over the plain-old console. Below is a list of key advantages of our plugin:

- Event of level WARN and ERROR are colored in orange and respectively in red.
- Go to the java class and line where any given logging request was issued by double-clicking on its output line.
- Filter events with logback's powerful filtering mechanism without changing your logging configuration.
- Change the output format dynamically whenever you chose to do so.
- Easy configuration (only one line in your logback.xml file).

### Installation

Installing the plugin requires a few steps. First get the plugin from our download page.

Once the transfert is complete, unzip the file called `ch.qos.logback.eclipse_VERSION.zip`. Place the folder found inside the archive in the following directory: ECLIPSE_INSTALL/plugins/ where ECLIPSE_INSTALL is the directory where you've installed Eclipse.

Relaunching Eclipse should load the plugin. To access the logback plugin, open the following menu: Window > Show view > Other... . You should see the Logback View nested in the Logback category. Selecting the view will add it to your workspace.

### Logging to the logback plugin

Logging to the logback plugin takes a single line of configuration in your logback.xml configuration file, as you can see below.

    <?xml version="1.0" encoding="UTF-8"?>

    <configuration>

      <consolePlugin />

    </configuration>

This element will trigger the creation of a `SocketAppender` that will send events to the localhost, on port 4321 by default. That's all it takes to run your software and log to the logback plugin. By default, logging events are not filtered, but please keep in mind that context-wide filtering in your logging configuration may affect the events that are recieved by the logback plugin.

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:

    <?xml version="1.0" encoding="UTF-8"?>

    <configuration>

      <consolePlugin port="4567" />

    </configuration>

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 a following section of this document.

### Using the logback plugin

Once the Logback View 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:

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.

The third button opens a sub-menu that lets you configure the logback plugin. This will be covered in a short moment.

When your software logs events, they are displayed in the logback view as shown below:

All events with the WARN level are displayed in orange. ERROR level events are displayed in red.

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.

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. You can click on the underlined parts of the stack trace to open an editor revealing the selected class.

### Configuring the logback plugin

On the right of the view, right next to the auto-scroll toggle is a button that opens a sub menu.

#### Preferences

The first item in this menu opens the plugin's preference window.

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:

- Relative time since launch
- Level of the request
- The thread name
- Name of the logger. The name is automatically shortened when longer than 25 characters
- The message of the request

An important point about this pattern is that, if it is modified, the changes are immediately reflected on the current content of the logback view. That means that if you would like to display an `MDC` value, or any other information that the `PatternLayout` provides, you can change it even after the logs have been requested.

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.

Finally, you can choose how many logging events should be displayed in the view before the list is trimmed. By default, the logback plugin will display 20'000 events. Once this number is reached, the plugin automatically drops the 30% oldest logs. Please note that changing this value to a too much higher value might lead to memory issues, or even crashing Eclipse.

#### Filters

The logback plugin lets you filter logging events when they are recieved. It uses the powerfull `EvaluatorFilter`objects that are available in logback. For detailled information about these filters, you might want to check the corresponding documentation 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.

The second item of the sub-menu on the right of the logback view opens the filter configuration window:

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.

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 `level`, `logger`, `message`, and several others. For a complete list of available variables, please refer to the chapter about filters in the logback manual.

The second and third informations that compose a filter are the action that will be taken depending on the result of the evaluation. Three actions are possible: ACCEPT, DENY or NEUTRAL. Setting a filter's reply to ACCEPT or DENY will prevent the plugin from evaluating any other filter and return a definitive result on the logging event.

Let us create a filter that will drop any request that has a level lower than INFO. A click on the New button creates a new filter. Enter the following informations in the corresponding fields:

- Expression: `level >= INFO`
- Action on filter match: `NEUTRAL`
- Action on filter mismatch: `DENY`

Here is what the window should look like, once you've saved the filter.

We've just created a filter that will drop any requests whose level is lower than INFO. Note the use of the NEUTRAL 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 INFO.

You may have noticed the two buttons on the left side of the filter windows labelled Up and Down. An important concept ruling the filters in logback is that filters are called in a chain. As we've seen above, a filter returning ACCEPT or DENY will stop the chain and have a direct impact on the logging event. It is sometimes important to manage the order in which filters are called to achieve a specific filtering policy.

You should now be ready to experience the logback plugin and use its functionnalites. If you have any question about its use, feel free to use the logback mailing lists.