Thursday, February 7, 2008

How to properly log errors, so that a user can send them to you

One of the biggest problems we had in the past in JGrass, was the fact that the users usually send an email to the list telling that JGrass "doesn't work". No other explenation, no way for us to understand. Since JGrass at that time was really buggy, it all got a mantainance nightmare.

The new JGrass has a solution to all this given by the Eclipse/Udig framework, which is the possibility to log the errors and let the user send the log to some poor guy that then has to understand what is happening. This is much better for us than the "doesn't work".

Obviously a developer will have to include some small snippet into his code to get the logging enabled. Here it is:

Step 1: insert the following code snippet into your Plugin Activator class

public static void log( String message2, Throwable t ) {
if (getDefault() == null) {
String message = message2;
if (message == null)
message = ""; //$NON-NLS-1$
int status = t instanceof Exception || message != null ? IStatus.ERROR : IStatus.WARNING;
getDefault().getLog().log(new Status(status, PLUGIN_ID, IStatus.OK, message, t));

Step 2: call the logging method from every needed part of your code, i.e. everywhere an exception is thrown and you would like to know it.
For example in the JGrass catalog plugin that would look like:

try {
// ... your code
} catch (Exception e) {
JGrassPlugin.log("JGrassPlugin problem:eu.hydrologis.udig.catalog.internal.jgrass
#JGrassMapGeoResource#getIdentifier", e);

this would be an exception thrown inside the
class: JGrassMapGeoResource
package: eu.hydrologis.udig.catalog.internal.jgrass
method: getIdentifier

You do not think I wrote that by myself, right?
The Eclipse template engine helps you in this. If you want it the same as above, just add the following template to the java->editor->templates list (all in one line):

${pluginActivator}.log("${pluginActivator} problem:
${enclosing_method}", ${throwable}); //$$NON-NLS-1$$

This will automagically insert the method-class-package, you just have to supply the plugin activator class name and the name of the exception.

If everything is done well then the user should be able to go under submit the log

And send us the content of everything that has been logged.

Please use that thing :)


Ishan De Silva said...

Have a look at this article for a simple CSS class that can be added to Blogger to display code snippets nicely.


moovida said...

Oh Ishan, that was a good comment and makes everything much more readable, thanks. And to show you that I care, I went over everything and applied.

Will you solve code syntax coloring next? :)