Tracing plug-ins in Eclipse

Traces allows an Eclipse plug-in developer to display information useful during the development and debugging stages. The information in a trace is certainly not useful for the end-user, so it should not be displayed by other means (like… in the eclipse error log view).

In a sense, trace information can be seen as println 2.0… it is usually ad-hoc information that is useful for reporting important events in a plug-in. measure execution times and/or can help in finding problems in the code like thread deadlocks.

Eclipse provides good support for tracing, including elements on the user interface to enable/disable and set the trace options. The mechanism is somewhat documented in the eclipse help, but I’ll try to provide some extra information on setting up tracing for your plug-in.

The first thing is getting to know the eclipse UI facilities. When testing a new plug-in, I assume that you’re launching a runtime eclipse application. It is not important if you’re debugging or running the application, it will print the trace either way… if enabled.

In the Run/Debug dialog, there are two things we care about:

  1. Passing the -debug command line argument to the launched eclipse application (using the Arguments tab).
  2. Selecting the traces we want to see using the Tracing tab.

Because your plug-in is not able to trace (yet), you can try enabling trace information for other plug-ins. One very verbose plug-in which is useful to check our set-up is org.eclipse.core.jobs.

Enabling tracing for org.eclipse.core.jobs.

Next, we want to define the tracing options for our plug-in. That is easily done by creating a file called .options in the plug-in project’s root.

The options file is a properties file where we can define the tracing options and their initial value. By convention, the options start with the plug-in id and the different options are separated by slashes.

#This is my comment
com.example.core/myoption=false

Also by convention, there is a global switch for the plug-in, called debug. Unless this option is set to true, no trace should be printed. Any other trace option should (by convention) have “debug/” prepended. So a typical options file might be like this:

#master switch
com.example.core/debug=false
# switch for tracing products added to/removed from the shopping cart
com.example.core/debug/shopping-cart=false

Remember, this is all by convention. If you look at eclipse plug-ins you’ll quickly realize that this is not mandatory… and rarely followed.

One final note on the options file. Why are all options set to false? The reason is that the file will be included with your plug-in, so you want to make the default tracing level to be quite limited… or non existant, just in case the end-user will pass the -debug flag to the application.

Now that everything is in place, you can launch the application again. In the Tracing tab you should now be able to modify the just defined flags in your options file.

Obviously, the changes in the launch options didn’t change a thing… our plug-in does not yet show any message. We need to provide the code for that.

The basic idea is very similar to logging, but we’ll use System.out instead of any logging framework (it is possible to use one, if you so desire). The first thing is to find a central place to trace. I tend to use an static method in the plug-in Activator to do so.

Before tracing, three things must be checked:

  1. The global debug switch has been enabled (-debug). This is accomplished with a call to Platform.inDebugMode().
  2. The plug-in switch has been enabled in the .options file (PLUGIN_ID/debug=true). A call to Platform.getDebugOption("PLUGIN_ID/debug") will tell you that.
  3. The switch to the specific trace has been enabled. Use the same call described above (with the specific trace option) to check that.

If everything is ok, then the trace message is echoed to standard out by using System.out.

Before closing… and advice on performance. It is important to avoid doing expensive job (or, if possible, any work at all) for tracing before checking if the trace is enabled. One of such expensive jobs is building the string to display (concatenating, calling toString()…). If you’re using Java 5 (or greater) you’re lucky, because you can use the varargs feature to avoid creating the message too early.

For example:

   /**
     * Sends trace messages to stdout if the specified trace option is enabled.
     *
     * This is intended only for developing and debugging. The use of variable
     * number of parameters avoids the cost of building the message when the
     * debug option is not enabled.
     *
     * @param traceOption
     *            the trace option enabling the message trace.
     * @param messageParts
     *            a variable number of objects with each part of the message to
     *            display.
     */
    public static void trace( String traceOption, Object... messageParts )
    {
        if ( !Platform.inDebugMode() )
        {
            return;
        }
        String globalTraceValue = Platform.getDebugOption( PLUGIN_GLOBAL_TRACE_OPTION );
        String value = Platform.getDebugOption( traceOption );
        if ( null != globalTraceValue && globalTraceValue.equals( "true" )
             && null != value && value.equals( "true" ) )
        {
            for ( int i = 0; i < messageParts.length; i++ )
            {
                System.out.print( messageParts[i] );
            }
            System.out.println();
        }
    }

This little help should let you start tracing your plug-ins and you can collect some timing information, visualize the execution flow, look out for race conditions…

About these ads

  1. Chiquillo, ¡cómo te lo curras!

    Así no me extraña que te llamen “el galáctico” ;)

    I wish I could understand a sigle word of your post…





  • My Open Source

  • Twitter Updates

    Error: Twitter did not respond. Please wait a few minutes and refresh this page.

  • Enter your email address to follow this blog and receive notifications of new posts by email.

    Join 9 other followers

  • Flickr Photos

    Apertura Agile Open Spain 2011 - 32

    Apertura Agile Open Spain 2011 - 31

    Apertura Agile Open Spain 2011 - 30

    More Photos

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: