How to leverage Eclipse tooling to diagnose customer
Lead, Workbench strategy for IBM internal tooling,
8 July 2003
This article describes strategies you can use to diagnose
customer-reported problems with Eclipse plug-ins. The most powerful of
these strategies is the ability to attach a debug session from one
Eclipse instance to a running instance of Eclipse on a remote host. The
strategies described in this article are valid for all products based on
Eclipse 2.x, such as WebSphere Studio Application Developer and
WebSphere Studio Site Developer.
So, you've written an Eclipse plug-in, and you've given it to a
customer -- and maybe that customer even paid for it! Sooner or later,
that customer is going to report a problem. Sometimes you'll be able to
tell what's going on just from a symptom report. Other times, the bug will
be thorny enough that you'll need to get more information from the user,
including his system configuration and some reassurance that he is
actually running the right version of your plug-in. In the worst case, you
won't even be able to recreate the problem in your environment; you'll
need direct access to the user's machine to really understand what's going
The good news is that, with a little bit of knowledge about workbench
tools and the way to access plug-in metadata, you can diagnose just about
any problem a customer may report against your plug-in. In this article,
you will see:
- How to get comprehensive information on the customer's workbench
configuration, including the plug-ins and features that are installed,
including the versions of each
- Where workbench errors are logged
- Where to find metadata specific to a particular plug-in
- How to debug the customer's environment from your own workbench
Eclipse provides an easy way to extract
configuration details for a running workbench instance (see also Figure
- Expand the Help menu in the workbench's main toolbar.
- Select About ... (the menu item text always begins with
"About", but may also contain product-specific text, as in "About IBM
WebSphere Studio Application Developer" or "About IBM WebSphere Studio
Site Developer" -- it all depends on what workbench flavor you are
- In the dialog that appears, press the Configuration Details
Figure 1. The About... dialog
A file named "Configuration Details" will open in the editor area of
the current perspective. This file contains the following information:
- All Java system properties under which the workbench JRE is running
- A complete list of installed features and plug-ins, and the version
- A log of Install/Update Manager activity
- The complete text of the workbench error log
Chances are, you'll want the customer to send you a copy of the entire
log. Fortunately, it's easy to save the log to the file system:
- Ensure that the editor in which the Configuration Details file is
open is in front and has focus.
- Select the File menu in the workbench's main toolbar.
- Select the Save Configuration Details As... menu item.
You can download an example of an actual configuration file from the
link in the Resources
section later in this article.
Notice also in Figure
1 that two other buttons are available in the About... dialog:
Feature Details and Plug-in Details. Pressing either of
these buttons causes a dialog to appear, containing a table view of
plug-ins/features and their versions. If you wish to quickly know whether
or not your plug-in is actually installed, or if the installed plug-in is
at a certain version, you may want to ask the customer to first check the
listings in these dialogs rather than have him send his entire
configuration details file.
The error log contains, in chronological order
(more-recent messages are at the end of the file), any messages and
exceptions that workbench and plug-in code has chosen to log. The
workbench automatically logs all uncaught exceptions to the error log.
The text of the error log is included in the Configuration Details file
that we generated in the previous section. Eclipse provides a graphical
view of the error log as well, from the Error Log view, which can be found
under the PDE Runtime view category. (To open a view, select Window
> Show View). The error log entries appear as rows in a table;
the most-recent entry is shown as the top row. You can view the details of
an entry by selecting a row, right-clicking, and selecting
Properties. In the properties dialog that appears, the details of
the particular log entry are on the Status Details page. See also Figure
Figure 2. The Error Log view
The error log file itself resides on the file system as .metadata/.log,
relative to the workspace root. The workspace root is often located
directly within the workbench install directory as a folder named
workspace (this is the Eclipse default workspace location). However, users
may configure their workspace root to be any folder in the file
Configuration Details file lists the features and plug-ins that are
installed in the workbench instance. However, it does not indicate whether
or not individual plug-ins are active.
Plug-ins are lazily loaded -- that is, their code is not loaded
into memory until that code is needed. The situation may arise, then, that
a plug-in is installed, but for some reason it has not been activated.
This means either that an error occurred when the workbench attempted to
load that plug-in, or that the plug-in's functionality simply has not been
The Plug-In Registry view lists the installed plug-ins, and indicates
whether or not each plug-in is active. To open this view, go to
Window > Show View. The view can be found under the PDE
The plug-ins are ordered by name (the name, not the plug-in ID, is
displayed). A plug-in is active if a "runner" icon is superimposed on its
Figure 3. The Plug-in Registry view
Figure 3 shows a Plug-in Registry view for a sample workbench
installation. Notice that not all plug-ins shown are active, just the one
named "Apache Axis", whose icon contains the "running" decoration.
The plug-in registry view is not automatically updated when a plug-in
is activated (or de-activated). To pick up the current enabled/disabled
state of the plug-ins, press the Refresh button in the view's title
bar. Otherwise, the view will continue to reflect the state of affairs
that existed when the view was first shown.
plug-in will commonly maintain metadata specific to itself. This metadata
may take any form: properties files, XML files, or even a proprietary
binary format. When the metadata is in human-readable form, it may be
useful to examine the metadata files directly.
Plug-in metadata resides on the file system under the
.metadata/.plugins directory, relative to the workspace root. Within the
.plugins directory are folders, one for each plug-in that is maintaining
its own metadata. Each folder's name is the same as the ID of the
corresponding plug-in. Metadata for that plug-in should be found within
The plug-in author may also have chosen to use the plug-in's default
preferences.ini file, which is located in the plug-in's install folder.
That install folder will contain the ID of the plug-in, and will be
located in the plugins directory in which the install took place
(generally, this directory can be found directly under the workbench
install root, but keep in mind that plug-in install locations are
Note that it is considered workbench best practice for a plug-in to
maintain its metadata in the locations we have just described. However,
you should be alert to the possibility that a plug-in author may have
chosen to defy this convention and store metadata in some other location,
such as the system temp directory.
The most powerful tool for servicing Eclipse
plug-in code is the Eclipse debugger's ability to debug a customer's
workbench, even when that customer's workbench is running on a remote
machine. You can use the Debug perspective of your Eclipse installation to
debug problems arising on a workbench instance running on any machine to
which you have network access. The remote workbench exposes its debug
information via an open socket (Listing
1 shows the Eclipse launch arguments you need to specify in order to
open a debugging socket). Once you have attached your debugger to the
customer's workbench, you may take advantage of the full power of the
Eclipse debugger by setting breakpoints, examining variables and execution
stacks, and more. (Extensive information on using the Eclipse Java
debugger is available in the workbench help, accessible via the
workbench's Help > Help Contents menu item).
Important: The source code in your workbench's workspace must
match the code that was used to build the plug-in version the customer has
installed. Before proceeding, you will want to determine the level of code
the customer has installed, and ensure that the code in your workspace
Once you have ensured that your source code is at the correct level,
the customer must launch his workbench instance with the following
arguments shown in Listing 1 to enable the attachment of a remote
debugger.Listing 1. Launching a remotely
eclipse.exe -vmargs -Xdebug -Xnoagent \
Make note of the value assigned to
address, which is the
number of the port that will be made available for attachment by remote
debuggers. In the example arguments above, the port number is 8000. Be
aware that the customer may be behind a firewall, and may have to
configure it in order for you to make your socket connection.
server=y specification indicates that the VM you have
just launched will wait for an incoming socket connection. By indicating
suspend=n, you allow execution of Java classes to continue.
suspend=y (or by omitting the
suspend specification altogether, since
y is its
default value), you would state to the VM you have just launched that you
want it to pause immediately before loading the main class.
Now, from your workbench, you must attach your debugger to the
- Switch to the Debug perspective (Window > Open
- From the main workbench menu, select Run >
Debug.... (Or, from the drop-down menu on the Debug button
in the workbench toolbar, select Debug...).
- In the launch configuration dialog, select the Remote Java
Application entry in the left view.
- Click the New button. A new remote launch configuration is
created and three tabs are shown: Connect, Source, and
- In the Project field of the Connect tab, type or
browse to select the project to use as a reference for the launch (for
source lookup). For remote-workbench debugging, you won't need to
specify a project.
- In the Host field of the Connect tab, type the IP
address or domain name of the host where the Java program is running. If
the program is running on the same machine as the workbench, type
- In the Port field of the Connect tab, type the port
where the remote VM is accepting connections. In our example, this value
is 8000, matching the port specified when launching the remote workbench
with the arguments in Listing
- The Allow termination of remote VM flag is a toggle that
determines whether the
Terminate command is enabled in the
debugger. Select this option if you want to be able to terminate the VM
to which you are connecting; in general, you will not need to do this.
- Click Debug. The launch attempts to connect to a VM at the
specified address and port, and the result is displayed in the Debug
view. If the launcher is unable to connect to a VM at the specified
address, an error message appears.
Figure 4. Launching a debug session, attached to a
You are now connected to the customer's workbench. You can ask the user
to perform any action you like in their workbench, and their workbench
state will be reflected in your debug session.
When debugging in this fashion, you may wish to take direct control of
the customer's desktop using a remote-control facility such as that
provided by WinVNC or Lotus Sametime, so that you can initiate actions on
the customer's workbench yourself.
If you can retrieve the correct level of code, you will be able to use
this technique in lieu of a tracing mechanism. Eclipse provides a nice
trace framework (see Resources
for a link), but like any tracing mechanism, it requires that code be
inserted in plug-in source to produce trace statements. That code will
have a performance penalty even when tracing is turned off and will
certainly increase your code footprint. Furthermore, you are at the mercy
of the developers -- if no trace statement was inserted at a point you
need, tracing is of no help to you. However, with the remote debugging
technique you don't have to worry about any of that -- you have the power
of full source-level debugging.
A suggested procedure for customer
In this article, you've seen a set of tools for
diagnosing customer problems with Eclipse plug-ins. Now, it's up to you to
decide how to use these tools in the way that's best for you and your
development group. One suggestion for a procedure for customer service
- If you cannot recreate the problem just from the bug report, have
the customer send you a copy of his configuration
file. Use this to ensure that your plug-in versions are the same as
the user's. You'll also want to examine the error
log closely for tell-tale messages and stack traces.
- If it looks like a plug-in activation problem, you may want to have
the user follow up for you by examining his plug-in
- If it looks like an error in the handling of your plug-in's
metadata, or is specific to the way the user has set up your plug-in,
have the user send you copies of the plug-in-specific
metadata files that you think are likely suspects.
- If all else fails, load the matching level of source into your
workspace, and remotely
debug the customer's workbench.
Of course, you'll want to be flexible and do what you need to do on a
case-by-case basis to get to the heart of a customer's problem.
Eclipse-based workbenches provide
for comprehensive serviceability with features that range from the viewing
of detailed configuration information to actual code-level debugging of a
- Join the Eclipse Platform community and download the Platform at eclipse.org. The Eclipse Platform
source code is licensed under the Common Public License. At eclipse.org,
you'll also find a glossary of terms and descriptions of Eclipse
projects, along with technical articles and newsgroups. The Eclipse
Platform white paper details the major components and functions of
- Download a sample
- Download the Eclipse Platform Plug-in SDK at the eclipse project
- Read about the Eclipse
- Browse the Eclipse
- Learn the gory details of plug-in loading by looking at the effort
to improve Eclipse
- For an introductory article on the Eclipse Platform and how it
works, see the developerWorks article "Working
the Eclipse Platform" by Greg Adams and Marc Erickson.
- To get started with developing applications using the Eclipse
Platform, see the developerWorks article "Getting
started with the Eclipse Platform" by David Gallardo.
- If you're interested in creating your own Eclipse plug-ins, see the
developerWorks article "Developing
Eclipse plug-ins" by David Gallardo.
- For an understanding of how to manage source code versions in
Eclipse, see the developerWorks article "Sharing
code with the Eclipse Platform" by Pawel Leszek, which describes in
detail the CVS version control integration interface that ships with the
- To learn more about the built-in debugging features of the Eclipse
platform, see the developerWorks article "Debugging
with the Eclipse Platform" by Pawel Leszek.
- Find more resources for Eclipse users on
Jan Kratky has been developing with Java since its
1.0 release. He's the lead for the workbench strategy for IBM
internal tooling. You can reach him at kratky at