Monitor Guide

The goal of the Bionanny project is to monitor existing, and real, Web Services. How to do it? There are several ways, as usually...

Whichever way is used, the goal is always to change Axis's server configuration file (a file webapps/axis/WEB-INF/server-config.wsdd) - where Axis lists all deployed Web Services - and to add there (or sometimes to remove from there) Bionanny monitor handlers. The Axis provides an AdminClient, a program that changes the server configuration file. You need only to provide so-called deployment descriptors (in XML) and give it to the AdminClient. The syntax of the deployment descriptors is described in the Axis User Guide (and you will not need to know unless you wish to construct or edit them manually). Here is anyway an example:

<service name="Blanka" provider="java:RPC">
  
  <requestFlow>
    <handler type="bionanny_monitor"/>
  </requestFlow>
  <responseFlow>
    <handler type="bionanny_monitor"/>
  </responseFlow>

  <parameter name="allowedMethods" value="*"/>
  <parameter name="className" value="org.bionanny.samples.SleepingEchoImpl"/>
  <parameter name="scope" value="application"/>
</service>

The colored code is a monitor handler (assuming that elsewhere in the Axis configuration file is defined a monitor handler named bionanny_monitor).

So what are the options? Before going there, be aware that all of them treat only Web Services deployed in the Axis environment (and therefore written in Java). At the moment, there is no similar way to do it for Perl, SOAP-Lite based, Web Services. But we need to find something soon...

	A command-line client DeploymentAdmin

The command-line client is represented by class org.bionanny.server.DeploymentAdmin and can be started by:

build/run/run-deploy-client

Usually, you run it in two steps. First, it creates a file with all already deployed services (it reads it from the Axis configuration file you put on its command-line):

build/run/run-deploy-client -c ...webapps/axis/WEB-INF/server-config.wsdd \
                            -l \
                            -o services.list

Now you can edit the resulting file (services.list) and remove names of services you do not wish to be monitored. Then, you call the program again in order to create new deployment descriptors for all remaining services in the list. It keeps all their existing deployment parameters (but it does not keep potential other, non-Bionanny, handlers - this should be fixed...):

build/run/run-deploy-client -c ...webapps/axis/WEB-INF/server-config.wsdd \
                            -s services.list \
                            -o deploy.wsdd

Now you have a new deployment descriptor (deploy.wsdd) that can be sent to the Axis AdminClient (you may need to add other parameters if your Tomcat is not listening on the port 8080 of the localhost):

build/run/run-any-client org.apache.axis.client.AdminClient deploy.wsdd

And that's it. Restart your Tomcat and call your services, and Bionanny will monitor them.

The same client can create deployment descriptors that can be used for removing monitors from deployed services. Just use option -u.

Using this command-line DeploymentAdmin client has advantage if you need to do some manual changes between individual steps. otherwise, the recommended way is to use Ant targets (they use the same client, by the way):

	Ant targets

Even with Ant you have more options - depending how many and which services you wish to monitor. Just remember, that the following Ant targets can only add monitor handlers to the services that have been already deployed (it is not a Bionanny's purpose to deploy regular Web services; the Axis AdminClient can do it).

The first option is to define services that you wish to be affected by a list of properties:

add-monitors

This target adds Bionanny monitor handlers to all services whose names appear in the properties with the following pattern: add.monitor.to.<service-name>. For example, this adds monitor to the services Version and Sumak:

./build-dev.sh -Dadd.monitor.to.Version=true \
	       -Dadd.monitor.to.Sumak=true \
	       add-monitors
	

remove-monitors

Similar as above - but now it removes monitors and it uses properties with pattern: remove.monitor.from.<service-name>. For example:

./build-dev.sh -Dremove.monitor.from.Version=true \
	       -Dremove.monitor.from.Sumak=true \
	       remove-monitors
	

The second alternative is to have a file whose each line contains a name of a service you wish to be affected:

list-deployed

It creates such file, a list of (almost) all deployed services in your Tomcat. The name of the file is taken from the property deployed.services.list (default file name is simply deployed.list). You can manually edit such file (blank lines and comment lines starting with '#' are ignored) before calling next Ant targets:

add-monitors-by-list

It adds monitor to services whose names are listed in a file. The file name is expected to be in the property deployed.services.list (default file name is the same as above - deployed.list. For example:

./build-dev.sh -Ddeployed.services.list=my.services \
	       add-monitors-by-list
	

Using the default name, you can call:

./build-dev.sh list-deployed
	

then edit file deployed.list, and call again:

./build-dev.sh add-monitors-by-list
	

remove-monitors-by-list

It removes monitors from the services whose names are listed in a file. Again, the file name is expected to be in the property deployed.services.list or a default file name deployed.list is used.

The last option is to add monitors to all deployed services:

add-all-monitors

It adds monitors to all deployed services.

remove-all-monitors

It removes monitors from all deployed services.