Introduction

In software engineering and hardware engineering, serviceability is also known as supportability, and is one of the -ilities or aspects. It refers to the ability of technical support personnel to debug or perform root cause analysis in pursuit of solving a problem with a product. [ http://en.wikipedia.org/wiki/Serviceability]

One of the feature of Serviceability includes the logging of state and the notification of the user.

Eclipse already provides different framework to manage the Log file as well as Dialog to notify the user. In Eclipse 3.3 we introduce a framework that will make the logging and Dialog consistent across the Eclipse platform. This new framework also allows provider to plug-in their diagnosis tools, providing extra value to the user.

This paper will explain the best practices a developer should follow to exploit this new framework appropriately using the IStatus class. The second part will explain to plug-in provider how to exploit the new ‘StatusHandler’ model, allowing them to contribute to the user interface as well as managing the IStatus we are about to show or log.

Before we investigate IStatus, we need to agree on a couple basic principle about logging and error message rendering.

Messages

A message is the principal information the user will see in the log or in the User Interface. A message that is logged is supposed to be user consumable and thus follow the same readability and globalization rules as a String rendered in a menu.

Message content

There is tons of information on how to create a usable message. We rely on your Software Engineering experience to void messages like: ‘internal error, please see log’.

Provide additional information in your message

We recommend you provide two other pieces of information when you create a message.

An explanation to the message. This is also a String that will provide more information to the user than a one liner message. The explanation should not be too technical, yet provide more value than the message text itself. Once again, there is information available on the web.

A recommendation of the message. This is a String that will tell the user what he/she should do. When you write this part, put yourself in the shows of the user and answer the following question: “ok, now what do I do ?”

Attempt to use a unique identifier

Unique identifier could be an int or a String that uniquely tag the message. There are two main reasons why you want to add a unique identifier to your message.

It is easier to search a knowledge base with a unique int than the full text of the message.

Because messages are translated, a user in a foreign country may send your support team a translated message. If you do not have a unique identifier, it will be difficult for your team to translate it back into the original language.

Developing messages in eclipse: using the NLS.bind method

Eclipse provides a great mechanism to manage your messages from within your Java code. Look at the NLS class

About logging and Error Dialog

The concept of a LogRecord

While a message is important, we need to realize it can occurs in many situation. I do not mean by that you should reuse a message in different places in your code..(it is a big no-no). I mean this message will occur on a certain machine at a certain time. This is what we call the ‘metadata’ around the message. This encompasses things like the timestamp, the thread identifier, the ip of the machine etc etc…

Example of such record are found in java.logging.logging.LogRecord from the JSR specification. Other logger like Apache Log4J currently use an Object as a record.

Eclipse does not provide the concept of a record in itself yet. So we usually end up writing our own method like debug(String) or warn(String) in our plug-ins. The equinox team is working on proving a full fledge logging framework, including the concept of a LogRecord in future releases.

NotaBene: The previous sentence is pure speculation as the team is currently investigating…

Best practices for logging

There is a lot of debate about what to log and what not to log.

If you log too little, it will be difficult to troubleshoot a problem. In some cases we will have to reproduce the problem in debug mode (allowing trace to be persisted). In the worse case scenario, if you cannot reproduce the issue, you will have to ship an instrumented version of your code to the client.

If you log too much, a couple things can happen

You could fill the hard drive with information and slow the process of your application

You will scare the product administrator who will see tons of 'possible' errors fill the log.

There are couple best practices I gathered during my years of Support Engineer.

Rule #1: if you show it, log it
The rationale is that if you do not log it, we have no persistence of the issue. If the user closes the Dialog and closes support, we will have to reproduce the problem.
Of course, in the case of a client-server environment, you do not have to log it in both places. If the message comes from the server, the client part can *just* present the message that will contain information about the real log record in the server log, so the administrator can retrieve it. Still I would recommend you save the message only (not the whole record) in the client environment, in case the clients forgets the correlator identifier to the server log.
Another possibility is to log the message at a DEBUG or TRACE level. Remember to be cautious or you will end up in Scenario #1 : Logging too little.

Rule #2: Log even expected exception
Some exceptions are expected in your environment. For instance, if you connect to a database using JDBC, you may encounter the java.sql.SQLException. It may be an exception you can recover from (i.e. StaleData) or one you cannot recover from (Server is down).
You should not log the StaleData exception or the log will contain too much information. The user/administrator is not interested about your internal code and how you recover.
Yet you should log the unexpected exception.
We recommend you log the message of an expected exception only, not the whole stackTrace, but at a WARNING or DEBUG level.

Other technique exists that keep a statistic view of your expected errors. This allow an administrator to realize, for instance, that the application is getting a lot of StaleException between 8pm and 9pm on Friday.

Rule #3: ZZZZZZZZZZZZZZZZZZZ I DO NOT HAVE A RULE #3 :( ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ

In the first part of this paragraph, we will describe the best practices a developer should use to log or render an IStatus.
In the second part of this paragraph, we will explain the best practices to create your own StatusHandler.

Using the new Eclipse status handler API

First we will present the new StatusManager class and its API. Then we will explain how you could modify your existing code to use the new features of the framework.

Calling the StatusManager handle method

Calling the new framework is straight forward.
Once your IStatus is created, you pass it to the singleton instance of the class StatusManager.
You can specify if you want the message to be logged (LOG) and.or shown (SHOW).

Remember the Handler has the last decision about showing and logging.
Consider the previous information as a hint to the handler, but do not rely on them for your execution.

Replacing your call to ErrorDialog, MessageDialog

Eclipse provide different API for logging and showing an error message. Here is a list of the Available API and their replacement using StatusManager

Replacing your call to ILog

Developing a StatusHandler

In this section, we will explain how to extend the Status handler framework. There will be a unique extension per application.

A StatusHandler is the counterpart of StatusManager.
As a developer, you will call the StatusManager code, passing the IStatus. The StatusHandler will handle the IStatus based on its policy.
For instance, a StatusHandler can determine if they need to be shown and/or logged.
A StatusHandler can decide to send an email to an administrator.

Developing an ErrorSupportProvider

Registering your ErrorSupportProvider

To Register your SupportArea, you must call the following code

Policy.setErrorSupportProvider(<instance of org.eclipse.jface.dialogs.ErrorSupportProvider>);

We recommend you do it in the Activator class of your bundle, in the start method.
Of course you can change it later, for instance in your handle method.
In that case, there is no contract that the ErrorSupportProvider you set will be the one receiving the IStatus your are processing.

Implementing the createSupportArea method

Implement the createSupportArea method, returning the control you want to show the user.

public Control createSupportArea(Composite parent, IStatus status) {
parent.addDisposeListener(this); // get notified so we can clean our SWT widgets
// if the dialog is too short, make it taller
ensureMinimumHeight(parent.getShell());
toolkit = new FormToolkit(parent.getDisplay());
toolkit.getHyperlinkGroup().setHyperlinkUnderlineMode(HyperlinkGroup.UNDERLINE_HOVER);
toolkit.getColors().initializeSectionToolBarColors();
...
}

We highly recommend you implement an IDisposeListener to clean up after yourself, when the ErrorDialog is closed.

The flow

When a IStatus needs to be handled, the StatusManager will retrieve the StatusHandler associated with the application.
It will pass the StatusAdapter to the handle method.
An Error dialog will open if you called the super.handle() method with a hint of StatusManager.SHOW.
When an IStatus is selected, the ErrorSupportProvider registered in the Policy will be called.
StatusManager will pass the IStatus to the ErrorSupportProvider.createSupportArea.