 | Level: Intermediate Jan Kratky, Lead, Workbench strategy for IBM internal tooling, IBM
08 Jul 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 on.
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
Workbench configuration
Eclipse provides an easy way to extract configuration details for a
running workbench instance (see also Figure 1):
- 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 using).
- In the dialog that appears, press the Configuration
Details button.
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
of each
- 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.
Workbench error log
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 2.
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 system.
Plug-in registry
The 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 accessed yet.
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 Runtime category.
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 plug-in icon.
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 metadata
A 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 folder.
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 configurable).
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.
Debugging remote workbenches
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 matches.
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 debuggable workbench
eclipse.exe -vmargs -Xdebug -Xnoagent \
-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
|
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.
The
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. By
specifying 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
customer's session:
- Switch to the Debug perspective (Window > Open
Perspective).
- 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 Common.
- 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
localhost.
- 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
1.
- 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 remote workbench
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 service
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 is:
- 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
registry view.
- 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.
Conclusion
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 customer's installation.
Resources
- 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 Eclipse.
- Download a sample configuration file.
- Download the Eclipse Platform Plug-in SDK at the eclipse
project downloads page.
- Read about the Eclipse trace framework.
- Browse the Eclipse
plug-in registry.
- Learn the gory details of plug-in loading by looking at the effort
to improve Eclipse
performance.
- 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 Eclipse Platform.
- 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 developerWorks.
About the author | | | 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 us.ibm.com. |
Rate this page
| |
