SourceFiles.org - Use the Source, Luke

RUE - Resource Utilization Explorer
Remus Pereni
Ver. 0.2 / 23 Oct 2000

Introduction

1.1. Purpose

Monitorization and visual tracking of some of the parameters from a Java Enterprise Server is vital for understanding how a system behaves/performs under some circumstances.

In this idea, RUE is intended to be used as a general, local or remote, monitoring tool (performance / resource) for any Java based server .

Using CORBA it's functionality could be extended also to the non Java servers (we try to come up with some reference implementations for Apache). Also we would like to extend RUE's functionality in the general programs profiling sphere.

RUE, as any monitor tool focuses on two issues:

Data extraction
Data representation

1.2. Data extraction

The first issue is acquiring the data. We define a data channel as a source of data. A server can provide one or more data channels. Because a data channel depends on a system (server), at any one moment it may or may not exist, so a data channel can not be considered persistent.

To provide a higher level of abstraction every data channel has an associated data channel factory, which is in charge of creating the data channel and providing some informations about the data being monitored: name of the channel, type of the channel, info, measuring unit, highest possible value (for percent calculations) and so on. A data channel factory can be persistent.

The main problem is that any probe/sonde disrupts the monitored environment, changing in this way the monitored data. We can't avoid that, but we can minimize the impact by moving as much of the monitorization code as possible to a remote computer, therefore RUE can work both with local data channels as with remote data channels.

In order to access a data channel factory, without knowing or caring that the factory is locally or remote JNDI(Java Naming and Directory Interface) is used for seeking and getting a instance of the factory.

Loading the data source factories in RUE is very simple and can be done in the rue XML configuration file (rue.xml) by specifying directly a class (which implements the data source factory interface):

<load-channel-factory class-name="data_source_factory_class_name"/>

Example

<load-channel-factory class-name="ro.nolimits.rue.RueTestDataChannelFactory" />

in the "data-channel-config" section.

Another way to load the data channel factories is to specify a JNDI domain to be searched:

<scan-domain name="a_name_for_the domain"> <param name="java.naming.factory.initial" value="the _initial factory"/>

  <param name="java.naming.provider.url"     value="theprovider_url" />
                 any other paramethers needed to get a naming context

</scan-domain>

Example

<scan-domain name="localhost-rmi">
<param name="java.naming.factory.initial" value="com.sun.jndi.rmi.registry.RegistryContextFactory"/> <param name="java.naming.provider.url" value="rmi://localhost/" /> </scan-domain>

Any data source factory binded to this domain will be acquired.

Storing the data values during one session is also possible due a temporary history kept in memory, who's saving rate can be configured by the RUE configuration file (rue.xml).

1.3. Data representation

Maybe the most difficult task in a monitoring program is the proper representation of the acquired data, this mostly because you will never know what values are going to be displayed, and especially because you might need to fit in the same display very different kind of data.

To overcome this problems, RUE allows a plug-in based display system, if the way it works doesn't fit your needs it's very easy to make your own data viewer and to load it in.

Default Rue provides two data viewers. A status bar data viewer which represents each data source as a bar used mostly to represent percentage values, and a chart data viewer.

At this moment there is also a report available, which produce an html file with the graphical representation (as a chart) of the monitored data channels. In the near future there will be more reports available, also we are working on a system to allow custom reports to be produced.

2. Installation

Basically after you unpack RUE, all you have to do to run it as application (for applet consult the applet section in config) is to set the RUE_HOME environment variable to point ro RUE directory and to edit the rue.xml config file to set your preferences. The most important thing to set (among the scan domains and load interceprtor sections) is the html-viewer, since that is used to view the help and also the generated reports and maybe the history-save-rate which determines the resolution of the history data (the report is generated based on them).

RUE depends on the next libraries:

XML - configuration file and later reports & exports/imports

castor-0.8.8-xml.jar
xerces.jar

JNDI

jndi.jar
providerutil.jar

JNDI/RMI

rmiregistery.jar

Report

JpegEncoder.jar

ANT- building

ant.jar
xml.jar

After you past the configuration phase you can start rue using the start.bat or start.sh available from the bin directory. As a note, do it might work, I recommend that all executables (either bat or sh) to be runed from the RUE root directory.

Ex: if you installed RUE (windows) at "c:\work\rue" then your RUE root directory would be "c:\work\rue" to start RUE:

bin\start

to build RUE:

bin\build

3. Configuration

3.1. The configuration file

RUE has an rue.xml configuration file which is used to store some of the runtime informations and allows to specify the data viewers & data channel factories to be loaded.

If RUE is not started from it's directory you have to specify a RUE_HOME environment variable. This also can be done at runtime by

appending

-DRUE_HOME=<where you installed rue>

Example: -DRUE_HOME=/devel/rue

to the start line (in the test.sh or test.bat).

Here it is a sample configuration file:

<?xml version="1.0"?>
<rue-config>

<refresh-rate>300</refresh-rate>

<html-viewer>kdehelp</html-viewer>

<!-- Every x sample is stored in the history, this value gives the

  history/reports resolution           -->
      <history-save-rate>4</history-save-rate>

      <color-generator-config>
          <color-space-dim>100</color-space-dim>
           <color-step>20</color-step>
  <!-- The start color -->
           <XMLColor b="0" r="95" var-name="start-color" g="0"/>
       </color-generator-config>

       <viewer class-name="ro.nolimits.rue.StatusBarDataViewer">
           <param value="true" name="show_grid"/>
       </viewer>
       <viewer class-name="ro.nolimits.rue.ChartDataViewer">
           <param value="true" name="show_grid"/>
           <param value="Fit" name="zoom_factor"/>
           <param value="15000" name="time_per_division"/>
       </viewer>

       <data-channel-config>

<!-- you have two options to load the data channel factories

with load-channel-factory, which simply tries to instantiate the factory
you give enough information through scan-domain (the name is not important) and the param name - value pair, so a JNDI InitialContext will be created and all the DataChannelFactories found in the provider.url will be created. You can add as much -load-channel-factories and scan-domains as you want -->
<load-channel-factory class-name="ro.nolimits.rue.RueTestDataChannelFactory"/> <load-channel-factory class-name="ro.nolimits.rue.RueTestDataChannelFactory"/>

           <scan-domain name="localhost-rmi">
                  <param name="java.naming.factory.initial" value="com.sun.jndi.rmi.registry.RegistryContextFactory"/>
                  <param name="java.naming.provider.url"   value="rmi://localhost/" />
          </scan-domain>

</data-channel-config>
</rue-config>

3.2. Running it as applet

Running RUE as applet is a little bit more difficult because of the security constrains imposed by most java aware browsers, and the lack of uniformity between them. Basically RUE does what no applet is normally allowed to do:

read system properties - some things can be customized, for instance the way Castor generates the config file can be influenced by the contents of a castor.properties file in the users home directory, ...
read files from the local system - the configuration file, for instance
write files to the local system - again the configuration parameters can be saved in a local file, for a later use. Also the report is generated locally
connect to different hosts than the applet was loaded - in order to get the data channels

3.2.1. Appletviewer

In order to run RUE as applet in appletviewer you have to make sure that you grant RUE some rights using the java policy mechanism (For more informations see:
http://java.sun.com/products/jdk/1.2/docs/guide/security/.

This can be done creating a .java.policy file in your home directory (under Windows this is :WIN_DIR\Profiles\YOUR_PROFILE\ or if this directory doesn't exist then in the WIN_DIR). Also is possible, but not recommended, to add this lines in the JAVA_HOME/jre/lib/security/java.policy file.

In the .java.policy you have to add:

grant codeBase "http://<applet_URL>/-" {

permission java.security.AllPermission; };

Example

grant codeBase "http://localhost/test/-" {

permission java.security.AllPermission; };

This grants rue all the rights, therefore it is not recommended. A better approach is to especially grant the rights

grant codeBase "http://<applet_URL>/-" {

       permission java.util.PropertyPermission "java.home", "read";
      permission java.io.FilePermission "/-" , "read";
      permission java.io.FilePermission "/-" , "write";
      permission java.io.FilePermission "/-" , "execute";
      permission java.awt.AWTPermission "showWindowWithoutWarningBanner";

};

3.2.2. Netscape

There is no more signed jar support with this version of RUE. The reason for this decision is that there are classes (like jndi.jar or rmiregistry.jar) which do make for instance network connections and therefore need to be signed. Because this classes where made by JavaSoft I don't think I have the rights to change them (sign them). In this idea the whole signing strategy is useless.

However there is a solution to outcome this inconvenient. In the Netscape home directory there is a file called "prefs.js" or "preferences.js". All you have to do is (before running RUE) add this line in the file:

user_pref( "signed.applets.codebase_principal_support", true)

When the applet is started you will be prompted to grant specific rights to the applet.

If you want to deploy RUE there are methods to do this automatically. In the html file a small java script could be embedded to do the changes, but the whole page have to be signed. For details about how to sign html pages for Netscape you can follow this link.

3.2.3. Internet Explorer

The first thing you have to do (unfortunately) when you want to run RUE is to install the IBM rmi patch available here. This is because the JVM provided by MSIE leaks support for RMI.

The problems enlisted at the Netscape point are true for MSIE. In this idea the most simple solution to run RUE is to deactivate the security for java applets (at least while you run RUE). You can do this by:

Choose from the "Tools" menu "Internet Options".
Click on the "Security" tab.
Select "Internet" or "Local Intranet" (depending where your site is)
Click the "Custom Level" button
From "Settings" select from "Microsoft VM" "Java permissions" -> "custom"
A click the "Java Custom Settings" button
Select the "Edit" tab
Put "Run Unsigned Content" on true

3.3. Interceptors

Staring with version 0.52, interceptors (sensors) are packages separately. Installation instructions will be available with every interceptor (sensor).

4. Frequent Asked Questions

4.1. when I start Tomcat or when I try to bind a DataChannel or DataChannelFactory to the rmiregistry. Why I get java.rmi.UnmarshalException, java.lang.ClassNotFoundException

First make sure when you started the rmiregistry you had in the classpath all the needed jar's. Strangely when I am in Linux I only need to have rue-xx.jar and rue-tomcat-xx.jar. When I am in Windows there also have to be rmiregistry.jar and jndi.jar

If it still not working try:

When starting the server, the java.rmi.server.codebase property must be specified, so that the stub class can be dynamically downloaded to the registry and then to the client. Run the server, setting the codebase property to be the location of the implementation stubs. Because the codebase property can only reference a single directory, make sure that any other classes that may need to be downloaded have also been installed in the directory referenced by java.rmi.server.codebase. The codebase might be specified in the java comand line like this:

java -Djava.rmi.server.codebase=http://myhost/~myusrname/myclasses/

The codebase property will be resolved to a URL, so it must have the form of "http://aHost/somesource/" or "file:/myDirectory/location/" or, due to the requirements of some operating systems, "file:///myDirectory/location/" (three slashes after the "file:").

Please note that each of the URL strings above has a trailing "/". The trailing slash is a requirement for the URL set by the java.rmi.server.codebase property, so the implementation can resolve (find) your class definition(s) properly.

If you forget the trailing slash on the codebase property, or if the class files can't be located at the source (they aren't really being made available for download) or if you misspell the property name, you'll get thrown a java.lang.ClassNotFoundException. This exception will be thrown when you try to bind your remote object to the rmiregistry, or when the first client attempts to access that object's stub.

NOTE: Sometimes on my Linux box (Mandrake 7.0 using jdk1.2.2 RC4) it still didn't found the stub's until i made a http mapping the the requested directory and set the codebase through http wich solved my problems.

4.2. source, i have the pop up menus, but i can not activate them. Under Linux, when I try to change the color or to get the info on a data

This happened also to me, but only with the blackdown JDK 1.2.2 RC 4, it doesn't happen with the IBM release of java. Also it doesn't happened with KDE2. Sometimes it works right if play you with your window manager focus settings.

4.3. When a dialog box appears RUE crashes.

Under Linux, if you have XFree86 4.0 ( Mandrake 7.1), the blackdown port of JDK 1.2.2 RC 4 seems to crash if a file dialog or a dialog in general pops up, this behavior doesn't happened with XFree86 3.3x or with IBM version of Java. Seems that it's a strange bug in the java port.

5. History

2000/10 - bug fix release 0.52, separation of interceptors from the RUE core
2000/05 - first public version of RUE (ver. 0.51) 6. Authors
Remus Pereni
Roy Wilson
Csaba Szabo 7. Thanks

This project would never be what it is without the peoples who where contributing with ideas, wishes. There are a few names I would like to mention :

Assaf Arkin - Exoffice Technologies
Emil Valkov - Exoffice Technologies
Louis Vadnay - noLimits Technologies
Michael J. Karajkoza
Nicole Wainwright - Collab.net
Pascal Belloncle - Exoffice Technologies
Sorin Iluti - noLimits Technologies

Also I would like to thank that SourceXchange, projects like this would, maybe, hardly became reality, without their support.

This project was entirely developed under Linux, using the blackdown port of JDK, thanks to all the people who made this possible.

8. TO DO

Plenty, for more informations visit the RUE development page available at: http://rue.sourceforge.net.

If you have suggestions or feature requests please send a email at: rue-bugs@nolimits.ro with the subject containing the word feature requests.

9. Copyright

http://www.nolimits.ro

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are

met

Redistributions of source code must retain the above copyright notice, this listof conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither name of the noLimits Technologies nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

10. Contact + Bugs

Project URL: http://rue.nolimits.ro

Development page URL: http://rue.sourceforge.net

Mailing lists:http://rue.nolimits.ro/mailman/listinfo/

Bug Tracking: rue-bugs@nolimits.ro

If you have any questions, wishes, bugs to report or ideas about how we could improve RUE, please don't hesitate to contact me at: remus@nolimits.ro

11. Links

http://rue.nolimits.ro

http://java.sun.com/products/jndi/

http://castor.exolab.org