Contents: Workbench configuration Workbench error log Plug-in registry Plug-in metadata Debugging remote workbenches A suggested procedure for customer service Conclusion Resources About the author Rate this article Related content: Debugging with the Eclipse Platform Developing Eclipse plug-ins Subscriptions: dW newsletters dW Subscription (CDs and downloads)

Jan Kratky
Lead, Workbench strategy for IBM internal tooling, IBM
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 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):

1. Expand the Help menu in the workbench's main toolbar.
2. 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).
3. 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:

1. Ensure that the editor in which the Configuration Details file is open is in front and has focus.
2. Select the File menu in the workbench's main toolbar.
3. 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.

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:

1. Switch to the Debug perspective (Window > Open Perspective).
2. From the main workbench menu, select Run > Debug.... (Or, from the drop-down menu on the Debug button in the workbench toolbar, select Debug...).
3. In the launch configuration dialog, select the Remote Java Application entry in the left view.
4. Click the New button. A new remote launch configuration is created and three tabs are shown: Connect, Source, and Common.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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:

1. 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.
   
   
2. 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.
   
   
3. 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.
   
   
4. 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.
  
  

What do you think of this document? Killer! (5) Good stuff (4) So-so; not bad (3) Needs work (2) Lame! (1) Comments?

developerWorks > Open source projects