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/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 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 framework/etc/org.ops4j.pax.logging.cfg, 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 environment, called the Karaf shell. This shell contains a number of commands that allow you to interrogate the application. Some useful commands include:

1. help - Lists all commands.

2. help c - Lists the help for command c.

3. list - Lists all bundles in the system.

4. ls - Lists the OSGi services provided or used by a bundle. For example, ls lists the services provided by all bundles, while ls 120 lists the services provided by bundle 120. Typing ls -u 120 lists the services used by bundle 120.

5. exports - Lists the packages exported by a bundle. For example, exports 120 lists all the packages exported by bundle 120. This is useful for checking if a bundle is inadvertently exporting internal packages that aren't meant to be public.

6. headers - This will display the information in the jar MANIFEST.MF file.

7. grep - Just like Unix grep. Use with a pipe. Very useful for sifting through the long list of bundles running; e.g. list | 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 list 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 your CyActivator. 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.

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 exports 42 command (where 42 is your bundle id). If you don’t see your service, then you should first check your CyActivator 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 found in the OSGi section of the pom.xml 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.