Using Byteman with the RHQ Agent
================================

In some extraordinary cases, it is useful to inject custom bytecode directly
in the agent code. This is useful, for example, if you want to do some
performance testing and trace the timing of certain method invocations to try
to determine where a slowdown in the code is occurring.

Profilers are normally the tools you use to do this; however, when an agent is
deployed out in the field or in production, sometimes it is not feasible to
install a profiler on the machine or the network where the agent is running.
Using Byteman might be the only alternative.

Another use-case which Byteman can be used is to inject code that artificially
causes faults in the agent or one of its plugins. This is useful if you want
to perform some tests on the fault tolerance and/or error handling of the
agent or plugins.

Byteman (http://www.jboss.org/byteman) is a small yet powerful utility that
can inject bytecode in an existing application.

The zip file where this README was found allows you to easily install Byteman
into your RHQ Agent and install a set of rules without downloading any
additional code or setting up additional configuration settings in your RHQ
Agent. The zip contains a file (byteman-rules.txt) that has two sample Byteman
rules (they trace the amount of time each plugin takes to calculate a
resource's availability status). If you want to write your own rules (or were
given a set of rules by someone trying to analyze your RHQ environment), just
edit that file with the rules you want and restart the agent with the included
rhq-agent-with-byteman.sh script. Your rules will get installed into Byteman
that runs inside the RHQ Agent.

See the Byteman documentation on how to write your own Byteman rules.

The zip file where this README was found already contains a version of Byteman
for you (version 1.3.0). If you want to use a newer Byteman, then download it
from here:

http://www.jboss.org/byteman/downloads.html

and copy the newer byteman.jar over the one that comes with the zip file where
this README was found.

To run the agent with Byteman installed, export the environment variable
RHQ_AGENT_HOME and run the rhq-agent-with-byteman.sh script:

> RHQ_AGENT_HOME=/my/rhq/agent/location
> export RHQ_AGENT_HOME
> ./rhq-agent-with-byteman.sh

