{{Virgo}} This page contains hints and tips for diagnosing problems with Virgo and Virgo applications.

+

{{Virgo}}

+

This page contains hints and tips for diagnosing problems with Virgo and Virgo applications.

+

__FORCETOC__

== Equinox Console ==

== Equinox Console ==

−

The Virgo shell is useful for inspecting the contents of the user region, but sometimes it is necessary to use a feature only available in the Equinox console or to inspect the contents of the kernel region. For example, at the time of writing, the Virgo shell is unable to display package wirings established by DynamicImport-Package.

+

The Equinox Console is useful for examining either the kernel framework or the user region framework.

−

To enable the Equinox console, you need to set a framework property like this:

To enable an Equinox console, you need to set a framework property, like this:

<pre>osgi.console=2402

<pre>osgi.console=2402

−

</pre>

+

</pre>identifying the port to use.

−

In the case of the user region, add this property to the file config/org.eclipse.virgo.kernel.userregion.properties. In the case of the kernel region, add this property to the file lib/org.eclipse.virgo.kernel.launch.properties.

+

+

In the case of the user region, add this property to the file <tt>config/org.eclipse.virgo.kernel.userregion.properties</tt>. In the case of the kernel region, add this property to the file <tt>lib/org.eclipse.virgo.kernel.launch.properties</tt>.

You can even enable an Equinox console in both regions at once, using two different ports of course.

You can even enable an Equinox console in both regions at once, using two different ports of course.

To use the console, telnet in:

To use the console, telnet in:

−

<pre>telnet localhost 2402

+

<pre>&gt; telnet localhost 2402

−

</pre>

+

</pre>

−

The most useful commands are "ss" to list all bundles, "bundle &lt;n&gt;" to display information about the bundle with bundle id &lt;n&gt;, and "help" to see other commands.

+

The most useful commands are ''ss'' to list all bundles, ''bundle &lt;n&gt;'' to display information about the bundle with bundle id ''&lt;n&gt;'', and ''help'' to see other commands.

+

+

When running in the user region, the Virgo shell commands are offered via the ''vsh'' command. Type ''vsh help'' to see a list of the shell commands available.

+

+

== Precision Debug logging ==

+

+

It is possible to turn on logging at various levels for specific classes (loggers) in Virgo. We illustrate this with a <code lang="java">'''FileSystemChecker'''</code> ''debug'' trace, which is part of the <code lang="java">'''HotDeployer'''</code> system.

This puts debug information in the <code lang="text">'''log.log'''</code> file in <code lang="text">'''serviceability/logs/virgo-kernel'''</code> directory.

+

+

Alternatively, set <code lang="text">'''appender-ref ref="LOG_FILE"'''</code> and the debug information goes in the general <code lang="text">'''log.log'''</code> file in the <code lang="text">'''serviceability/logs'''</code> directory.

+

+

In this case the sort of output you might see is (actual paths have been replaced): <pre>[2010-07-23 12:27:44.599] fs-watcher org.eclipse.virgo.kernel.deployer.hot.HotDeployer pickup - before check:

+

FileList(): [test.configuration.properties]

+

Known files: [/path-to-server-home/pickup/test.configuration.properties]

Known files: [/path-to-server-home/pickup/test.configuration.properties]

+

Monitored: [] </pre>

+

+

which is pretty verbose, so be aware that the log file may become quite large very quickly. In the standard <code lang="text">'''serviceability.xml'''</code> file the appenders used here write to "rolling log files" which are based upon size; so the total amount of logged information is bounded, though the log you choose can be swamped with information from one source.

+

+

The <code lang="text">'''serviceability.xml'''</code> file is just a logback configuration file, and all the Logback functionality is available. For more information see the [http://logback.qos.ch/manual/configuration.html Logback configuration] on-line documentation.

+

+

== Entry and Exit tracing ==

+

+

In the default '''<code lang="text">serviceability.xml</code>''' file the root logging level is '''<code lang="text">INFO</code>'''. This is reasonable: if a log entry is made at <b><code lang="text">INFO</code></b> level, one expects this to appear in the log under normal circumstances.

+

+

<code lang="text">Medic</code> (one of the Virgo repositories) is designed to set up logging, tracing and dumping, for use by the rest of the code, and achieves this partly by weaving in aspects that perform tracing at the entry and exit points of methods. These aspects are woven into the rest of the code so that they don't have to code them themselves.

+

+

The entry and exit level tracing aspects are carefully woven into the <code lang="text">kernel</code> and the server code (<code lang="text">web</code>) to avoid the logging code itself (recursion) and the low-level utility functions (<code lang="text">util</code> and <code lang="text">osgi-extensions</code>).

+

+

It traces entry and exit points at two levels: <b><code lang="text">DEBUG</code></b> for all <code lang="java">public</code> methods and <b><code lang="text">TRACE</code></b> for all other methods (package private and private). 'Getter' and 'Setter' methods (those beginning with <code lang="text">get</code> and <code lang="text">set</code>) are not traced at any level.

+

+

So, to see these entries you need to set the logging level to <b><code lang="text">DEBUG</code></b> or higher for the areas you are interested in.

+

+

You will see entries in the <b><code lang="text">serviceability/log/log*.log</code></b> files like this:<pre>[2010-07-29 16:40:31.342] main > public static boolean org.eclipse.virgo.kernel.core.BundleUtils.isFragmentBundle(org.osgi.framework.Bundle)

where the entry and exit points are marked with <b><code lang="text">></code></b> and <b><code lang="text"><</code></b> respectively, with the full class names of the method and its parameters supplied.

+

+

It is arranged that <i>any</i> exit from a method will be traced if its entry is, even if that was the result of an exception, so the entry and exit lines should always pair.

+

+

== Profiling ==

+

+

We use YourKit for profiling Virgo. The setup is simple and apart from adding the appropriate JVM options (described on the [http://yourkit.com/docs/95/help/agent.jsp YourKit site]) to JAVA_OPTS, all that is necessary is to add <tt>com.yourkit.*</tt> to the <tt>org.osgi.framework.bootdelegation</tt> property in <tt>lib/java6-server.profile</tt>. Note that YourKit has a [http://yourkit.com/docs/95/help/filters.jsp default filter] which excludes <tt>org.eclipse.*</tt>, so if you would like to profile the internals of Virgo then you'll need to disable this filter.

+

+

For a detailed break down of this process, please see the section below related to your operating system.

+

+

=== Linux / Unix ===

+

+

#Install YourKit to your PC. For the purposes of this guide, YourKit has been installed into <tt>/opt/yjp-9.5.4</tt>. You do not have to install YourKit into this directory to enable profiling with Virgo. It is just used as an example.

+

#Locate the directory where you have installed Virgo, create the following file and open it: <tt>bin/setenv.sh</tt>

+

#Edit the file <tt>bin/setenv.sh</tt> and add two shell variables: YJP_HOME and JAVA_OPTS.

<p style="margin-left: 3.5em;">'''Other *nix'''<br/>For other versions of Unix, use either one of the above options and simply alter <tt>-agentpath:$YJP_HOME/bin/os-arch/libyjpagent.so</tt> so that <tt>$YJP_HOME/bin/os-arch/libyjpagent.so</tt> points to the YourKit Agent library for your platform.</p>

+

<ol start="6">

+

<li>Locate and open the file <tt>lib/java6-server.profile</tt>. Towards the bottom of that file, there will be a section for ''bootdelegation''. Add the following value to that section, <tt>com.yourkit.*,\</tt><br/>

+

<p>For example:</p>

+

<div style="margin-left: 1.5em;">

+

<pre>

+

org.osgi.framework.bootdelegation = \

+

org.eclipse.virgo.osgi.extensions.*,\

+

org.eclipse.virgo.osgi.launcher.*,\

+

org.eclipse.virgo.kernel.authentication,\

+

com.sun.*,\

+

com.yourkit.*,\

+

javax.xml.*,\

+

org.apache.xerces.jaxp.*,\

+

org.w3c.*,\

+

org.xml.*,\

+

sun.*

+

</pre></div>

+

</li>

+

<li>Restart the Eclipse Virgo installation. The first line of the console output should read as follows.<br/>

<p>This means that the YourKit profiler has been enabled for the Virgo installation. If you do not see this line as the first line of the console output, please check the edits made to the bin/setenv.sh file and to the lib/java6-server.profile file in the previous two steps.</p>

+

</li>

+

<li>Start the YourKit application.</li>

+

<li>If you would like to profile the internals of Virgo, go to the ''Settings'' menu and select ''Filters''. Then scroll down the list till you see the entry for <tt>Eclipse</tt>. Unselect the checkbox next to that entry and click the ''OK'' button. '''Note''' You only need to perform this step once.</li>

+

<li>Look at the '''Monitor Local Applications''' panel, it should now contain an entry for the Eclipse Virgo server, labeled as '''Launcher'''. Click the link to start profiling Virgo and any bundles deployed to the server.</li>

+

</ol>

+

+

=== Windows ===

+

+

#Install YourKit to your PC. For the purposes of this guide, YourKit has been installed into <tt>C:\Program Files\YourKit Java Profiler 9.5.4</tt>. You do not have to install YourKit into this directory to enable profiling with Virgo. It is just used as an example.

+

#Right click on ''My Computer'' and go to ''Properties''. Click the ''Advanced'' tab and then the ''Environment'' button.

+

#Add a ''System Variable'' called YJP_HOME and set its value to the location where YourKit was installed. For this example, that is <tt>C:\Program Files\YourKit Java Profiler 9.5.4</tt>.

+

#Edit the ''Path'' system variable and append one of the following <tt>%YJP_HOME%\bin\win32</tt> for 32-bit Windows systems or <tt>%YJP_HOME%\bin\win64</tt> for 64-bit Windows systems.

+

#Locate the directory where Virgo is installed and create a file called <tt>bin/setenv.bat</tt>.

+

#Edit the file <tt>bin/setenv.bat</tt> and add a shell variable called JAVA_OPTS. Set the value to the following.

+

<div style="margin-left: 3em;"><source lang="bash">

+

set JAVA_OPTS="-agentpath:yjpagent=disablestacktelemetry,disableexceptiontelemetry,builtinprobes=none,delay=1000"

+

</source></div>

+

<ol start="7">

+

<li>Locate and open the file <tt>lib\java6-server.profile</tt>. Towards the bottom of that file, there will be a section for ''bootdelegation''. Add the following value to that section, <tt>com.yourkit.*,\</tt><br/>

+

<p>For example:</p>

+

<div style="margin-left: 1.5em;">

+

<pre>

+

org.osgi.framework.bootdelegation = \

+

org.eclipse.virgo.osgi.extensions.*,\

+

org.eclipse.virgo.osgi.launcher.*,\

+

org.eclipse.virgo.kernel.authentication,\

+

com.sun.*,\

+

com.yourkit.*,\

+

javax.xml.*,\

+

org.apache.xerces.jaxp.*,\

+

org.w3c.*,\

+

org.xml.*,\

+

sun.*

+

</pre></div>

+

</li>

+

<li>Restart the Eclipse Virgo installation. The first line of the console output should read as follows.<br/>

<p>This means that the YourKit profiler has been enabled for the Virgo installation. If you do not see this line as the first line of the console output, please check the edits made to the bin/setenv.sh file and to the lib/java6-server.profile file in the previous two steps.</p>

+

</li>

+

<li>Start the YourKit application.</li>

+

<li>If you would like to profile the internals of Virgo, go to the ''Settings'' menu and select ''Filters''. Then scroll down the list till you see the entry for <tt>Eclipse</tt>. Unselect the checkbox next to that entry and click the ''OK'' button. '''Note''' You only need to perform this step once.</li>

+

<li>Look at the '''Monitor Local Applications''' panel, it should now contain an entry for the Eclipse Virgo server, labeled as '''Launcher'''. Click the link to start profiling Virgo and any bundles deployed to the server.</li>

To enable an Equinox console, you need to set a framework property, like this:

osgi.console=2402

identifying the port to use.

In the case of the user region, add this property to the file config/org.eclipse.virgo.kernel.userregion.properties. In the case of the kernel region, add this property to the file lib/org.eclipse.virgo.kernel.launch.properties.

You can even enable an Equinox console in both regions at once, using two different ports of course.

To use the console, telnet in:

> telnet localhost 2402

The most useful commands are ss to list all bundles, bundle <n> to display information about the bundle with bundle id <n>, and help to see other commands.

When running in the user region, the Virgo shell commands are offered via the vsh command. Type vsh help to see a list of the shell commands available.

Precision Debug logging

It is possible to turn on logging at various levels for specific classes (loggers) in Virgo. We illustrate this with a FileSystemCheckerdebug trace, which is part of the HotDeployer system.

In serviceability.xml in the config directory simply add the following:

which is pretty verbose, so be aware that the log file may become quite large very quickly. In the standard serviceability.xml file the appenders used here write to "rolling log files" which are based upon size; so the total amount of logged information is bounded, though the log you choose can be swamped with information from one source.

The serviceability.xml file is just a logback configuration file, and all the Logback functionality is available. For more information see the Logback configuration on-line documentation.

Entry and Exit tracing

In the default serviceability.xml file the root logging level is INFO. This is reasonable: if a log entry is made at INFO level, one expects this to appear in the log under normal circumstances.

Medic (one of the Virgo repositories) is designed to set up logging, tracing and dumping, for use by the rest of the code, and achieves this partly by weaving in aspects that perform tracing at the entry and exit points of methods. These aspects are woven into the rest of the code so that they don't have to code them themselves.

The entry and exit level tracing aspects are carefully woven into the kernel and the server code (web) to avoid the logging code itself (recursion) and the low-level utility functions (util and osgi-extensions).

It traces entry and exit points at two levels: DEBUG for all public methods and TRACE for all other methods (package private and private). 'Getter' and 'Setter' methods (those beginning with get and set) are not traced at any level.

So, to see these entries you need to set the logging level to DEBUG or higher for the areas you are interested in.

You will see entries in the serviceability/log/log*.log files like this:

where the entry and exit points are marked with > and < respectively, with the full class names of the method and its parameters supplied.

It is arranged that any exit from a method will be traced if its entry is, even if that was the result of an exception, so the entry and exit lines should always pair.

Profiling

We use YourKit for profiling Virgo. The setup is simple and apart from adding the appropriate JVM options (described on the YourKit site) to JAVA_OPTS, all that is necessary is to add com.yourkit.* to the org.osgi.framework.bootdelegation property in lib/java6-server.profile. Note that YourKit has a default filter which excludes org.eclipse.*, so if you would like to profile the internals of Virgo then you'll need to disable this filter.

For a detailed break down of this process, please see the section below related to your operating system.

Linux / Unix

Install YourKit to your PC. For the purposes of this guide, YourKit has been installed into /opt/yjp-9.5.4. You do not have to install YourKit into this directory to enable profiling with Virgo. It is just used as an example.

Locate the directory where you have installed Virgo, create the following file and open it: bin/setenv.sh

Edit the file bin/setenv.sh and add two shell variables: YJP_HOME and JAVA_OPTS.

Other *nixFor other versions of Unix, use either one of the above options and simply alter -agentpath:$YJP_HOME/bin/os-arch/libyjpagent.so so that $YJP_HOME/bin/os-arch/libyjpagent.so points to the YourKit Agent library for your platform.

Locate and open the file lib/java6-server.profile. Towards the bottom of that file, there will be a section for bootdelegation. Add the following value to that section, com.yourkit.*,\

This means that the YourKit profiler has been enabled for the Virgo installation. If you do not see this line as the first line of the console output, please check the edits made to the bin/setenv.sh file and to the lib/java6-server.profile file in the previous two steps.

Start the YourKit application.

If you would like to profile the internals of Virgo, go to the Settings menu and select Filters. Then scroll down the list till you see the entry for Eclipse. Unselect the checkbox next to that entry and click the OK button. Note You only need to perform this step once.

Look at the Monitor Local Applications panel, it should now contain an entry for the Eclipse Virgo server, labeled as Launcher. Click the link to start profiling Virgo and any bundles deployed to the server.

Windows

Install YourKit to your PC. For the purposes of this guide, YourKit has been installed into C:\Program Files\YourKit Java Profiler 9.5.4. You do not have to install YourKit into this directory to enable profiling with Virgo. It is just used as an example.

Right click on My Computer and go to Properties. Click the Advanced tab and then the Environment button.

Add a System Variable called YJP_HOME and set its value to the location where YourKit was installed. For this example, that is C:\Program Files\YourKit Java Profiler 9.5.4.

Edit the Path system variable and append one of the following %YJP_HOME%\bin\win32 for 32-bit Windows systems or %YJP_HOME%\bin\win64 for 64-bit Windows systems.

Locate the directory where Virgo is installed and create a file called bin/setenv.bat.

Edit the file bin/setenv.bat and add a shell variable called JAVA_OPTS. Set the value to the following.

This means that the YourKit profiler has been enabled for the Virgo installation. If you do not see this line as the first line of the console output, please check the edits made to the bin/setenv.sh file and to the lib/java6-server.profile file in the previous two steps.

Start the YourKit application.

If you would like to profile the internals of Virgo, go to the Settings menu and select Filters. Then scroll down the list till you see the entry for Eclipse. Unselect the checkbox next to that entry and click the OK button. Note You only need to perform this step once.

Look at the Monitor Local Applications panel, it should now contain an entry for the Eclipse Virgo server, labeled as Launcher. Click the link to start profiling Virgo and any bundles deployed to the server.