Eclipse Tip: Don't Let Bugs Get Lost Without Trace, Page 2
Typically, a plug-in would first call Platform.inDebugMode(). This returns true if the platform was launched with the -debug argument. By convention, the plug-in should also check if the debug option <pluginId>/debug evaluates to true by calling Platform.getDebugOption("<pluginId>/debug"). This is considered the "root" debug option that determines whether a particular plug-in should enable tracing. Other arbitrary options may be used (by convention they should follow the pattern <pluginId>/debug/<option>). The PDE Launch dialog provides a Tracing tab that allows you to enable tracing (for example, launch the platform in "debug mode") and configure debug options for each plug-in. A plug-in must advertise which options it supports by specifying their default values in a .options file (note the leading dot), which must be located in the plug-in's root.
The example plug-in provided in the Resources section contains a small class (Debug) that can be used to implement simple tracing. Note that you should always check whether you are to generate a trace message before composing it, because not doing so could strain your resources unnecessarily. That is, rather than creating a generic trace method that takes arbitrary data to be logged and only then checks if tracing is enabled, do an if check before allocating any strings or other arguments for the message.
The example plug-in provided in the Resources section demonstrates both logging and tracing. It contributes a top-level menu (Logging & Tracing) with actions that perform various logging and error reporting activities. The plug-in also supports several sample tracing options.
To get started, import the attached archive into your Eclipse SDK 3.3 as an Existing Project; click File -> Import, and then select General -> Existing Projects into Workspace. Provide the path to the downloaded zip file and click Finish.
To enable tracing for the plug-in, first create a launch configuration for it. Click Run -> Open Run Dialog, and then select Eclipse Application and click New. Go to the Tracing tab and check Tracing, and then select and check com.developer.tracing. Also, check all its debug options on the right. Figure 2 shows the configured Tracing tab. Click Run and observe debug messages in the console view as you invoke the various contributed actions.
- Source code for the example—import the archive into your Eclipse SDK 3.3 as an Existing Project
- Plug-in Development Environment Guide: Error Log
- Platform Plug-in Developer Guide: Eclipse runtime options
- Eclipse FAQ: How do I use the platform logging facility?
- Eclipse FAQ: How do I use the platform debug tracing facility?
- EclipseZone: Using Log4J in Eclipse Equinox/OSGi
About the Author
Peter Nehrer is a software consultant specializing in Eclipse-based business applications and development tools. He is the founder of Ecliptical Software Inc. and a contributor to several Eclipse-related Open Source projects. He holds an M.S. in Computer Science from the University of Massachusetts at Amherst, MA. Peter can be reached at pnehrer AT eclipticalsoftware DOT com.