Diff for "Cytoscape_3/CoreDevelopment/Debugging"

Purpose

This document will attempt to provide some help for app authors and Cytoscape developers in understanding how to debug problems with Cytoscape. First we’ll describe the diagnostic tools available and then what to do in some common problem situations.

Diagnostic Tools

Log Messages

There are two places that log messages are currently configured, one is STDOUT (i.e. the console window where you ran cytoscape.sh/bat). The second place is in a file called “framework-cytoscape.log” found in the installation directory. We’ve attempted to partition the log messages by putting Cytoscape specific messages in the console and OSGi/Spring framework messages in the framework-cytoscape.log file. The primary purpose for this is that the framework messages are voluminous and not really useful until there is a problem.

The log levels and where log messages get directed are controlled by the file bundles/configurations/services/org.ops4j.pax.logging.properties, which is a Log4J configuration file. You can increase or decrease the verbosity of the log messages by editing this file and restarting Cytoscape.

OSGi Console

The console where you start your application will also start a small, OSGi specific shell, called GoGo shell. This shell contains a limited number of commands that allow you to interrogate the application. Some useful commands are include:

1. help - This lists all commands.
2. help XXX - This lists the help for command XXX.
3. lb - This will list all bundles in the system.
4. inspect - This allows you to inspect the state of bundles in the system. Read the help for this command (“help inspect”) for full details, but some useful examples are:
5. inspect s c 42 - This is short for “inspect service capability 42” where 42 is the bundle ID. This is extremely useful for determining whether or not an expected service is being provided.
6. inspect p c 42 - This will list the packages exported by bundle 42. This is useful for ensuring that no private code is inadvertently exposed.
7. inspect s r 42 - This will list the services required by bundle 42.
8. headers - This will display the information in the jar MANIFEST.MF file.
9. grep - Just like Unix grep. Use with a pipe. Very useful for sifting through the long list of bundles running: lb | grep my-bundle

Common Problems

This section will contain a non-exhaustive list of common problems encountered when developing and running Cytoscape 3.0.

The GUI/menu item/action/button/panel I expect isn’t there!

First, we assume that everything WAS working until you made your change.

The first thing to check is to make sure that your bundle has actually started using the “lb” command in the OSGi console. The bundle should be in the “Active” state. If it’s in a different state (e.g. installed), then there is likely a problem in how the bundle has been configured. If you type “start 42” in the OSGi console (assuming 42 is your bundle id), then you should probably see some sort of exception in the OSGi console. You may need to scroll through the exceptions for a while until you see the root cause.

Ok, if your bundle is “Active”, then the problem is likely in the Spring-DM configuration. The place to see this type of problem is in the framework-cytoscape.log file. First, search for exceptions here. If you see an exception then it’s just a matter of following the stack deep enough to find the root cause. In most cases, a bean (specified in bundle-context.xml) is not being constructed correctly, in which case you’ll need to examine the exception and XML to determine what isn’t correct.

In other cases, you may not see any exceptions in the framework-cytoscape.log. When you don’t see exceptions, this usually means that someone is waiting for a service to be provided that hasn’t yet been provided. The best thing to do is start at the BOTTOM of the framework-cytoscape.log file and search up for the word “wait” and more specifically a message indicating that one bundle is waiting for one or more unfulfilled dependencies. We start at the bottom because we want to most recent “wait” message, this is important because bundles start out of order meaning that you may see many waiting messages that will eventually get fulfilled. What you really need is the last message. Sometimes this is not obvious.

When it’s not obvious which service is missing, it is sometimes necessary to begin examining the bundles loaded in the OSGi console to see which services they are and are not providing. Here, the use of the “inspect” command, and in particular the “inspect s c 42” command, is very useful for determining whether or not something is being exported or not.

Once the missing service has been identified, the solution is to configure the bundle-context-osgi.xml file correctly.

Sometimes the problem is not that you’re missing a required service, but that you’re not exporting YOUR service correctly. In this case your best bet is to confirm that the service isn’t being exported by the bundle using the “inspect s c 42” command (where 42 is your bundle id). If you don’t see your service, then you should first check the bundle-context-osgi.xml to make sure it’s OK. If you think it is, then one option is to check the framework-cytoscape.log for exceptions related to your bundle. Just search for the name of your bundle and see what turns up. Another option is to stop your bundle and try starting it again on the OSGi console because if an exception is thrown it may show up in the console. To do this type “stop 42” followed by “start 42”. At this point, the problem may be in your java code and isn’t necessarily a configuration problem.

Other possible causes of a missing service could be that your OSGi metadata hasn’t been specified correctly. This can be done in many different ways, but in Cytoscape it’s usually done using the osgi.bnd file in the top level of most projects. Be sure you don’t have duplicate statements and that you’ve made what you want private. You can see the manifest information that OSGi sees using the “headers” command in the OSGi console.

Issues

List any issues, conflict, or dependencies raised by this proposal

Comments

• Add comment here…

How to Comment

Edit the page and add your comments under the provided header. By adding your ideas to the Wiki directly, we can more easily organize everyone's ideas, and keep clear records. Be sure to include today's date and your name for each comment. Try to keep your comments as concrete and constructive as possible. For example, if you find a part of the documentation makes no sense, please say so, but don't stop there. Take the extra step and propose alternatives.