Using The Agent Plugin

The agent plugin is used to manage the agent itself - you can monitor, configure and control the agent from the server GUI.
Because the agent can monitor its internal metrics, it allows you to track its behavior and ensure that it is operating properly. Like any other resource managed by RHQ, you can define alerts on this metric data which can be triggered when an agent starts behaving in an abnormal way. In addition, you can control the lifecycle of the agent by restarting it or shutting it down.

If you shutdown the agent, you will not be able to use the GUI to start it back up again because there will be no agent to receive the start command! Only shutdown the agent when you have no intention of starting it up again or if you are willing to manually log onto the agent's machine and start it from a shell console. If you need to reboot the agent, use the "restart" operation provided by the agent's launcher child service.

Inventoring The Agent Server and its Services

When you import the agent, you will get one server resource and several child services added to your inventory. Some of these services are platform-specific; that is, some services are only deployed in the agent when running on Windows or when running on UNIX. All of the resources provide specialized monitoring, configuration and control of the agent. These resources are described in more detail below.

Here's the typical resource hierarchy for the agent running on Linux and Windows (click thumbnails for larger images):

Here's the typical list of children for an agent server resource running on Linux and Windows (click thumbnails for larger images):

Server Resource

The main server resource provides monitoring, configuration and control functionality for your agent. You can configure the agent's internal components - these configuration settings correspond to the preferences defined in the agent-configuration.xml file and persisted on the agent machine as Java Preferences. You can control the agent by executing the several available operations on the agent server resource.

Note that the operations provided by the agent server resource normally do not affect the agent process in a direct way. This means you cannot kill the agent VM process, you cannot configure the agent VM's environment variables and you cannot configure the agent VM's JRE options. You do these things by working with the agent's child services, as defined below. The only exception is the "shutdown" operation, which will actually kill the agent process if and only if the agent is running as a background daemon service (if its running in a console window, the agent VM will not completely exit allowing the user to continue to execute prompt commands from the console prompt).

Common Services

These are the services that are common to all agents. Whether running on Windows or UNIX, all agents have these services as children to the main agent server resource.

Agent Measurement Subsystem

This service provides data on the measurement collection and reporting components in the agent. It can tell you information about the measurements being collected and sent up to the server.

Agent JVM

The Agent JVM "service" is actually considered a child "server" that provides additional child services that give you more fine grained monitoring and management of the VM that is running the agent and all its plugins, which includes the classloader, threading and memory management subsystems, among others.

Agent Environment Setup Script

Whether on Windows or UNIX, all agents have an environment setup script - they are just named differently based on the platform ("rhq-agent-env.bat if on Windows, rhq-agent-env.sh if on UNIX). This child service allows you to configure that environment variables that are set when you start the agent launcher script.

Java Service Wrapper Launcher (Windows-only)

If the agent is running on Windows, the agent will have a child service that controls the Java Service Wrapper. This is a third party library used to install and run the agent as a Windows Service. There is one main configuration for the Java Service Wrapper, and it is read-only (rhq-agent-wrapper.conf). These define the base set of configuration settings necessary for the agent to start and operate properly. However, there are two additional groups of configuration settings that you can use to customize your agent's environment. The Environment group defines/overrides environment variables that are used by the main configuration (note that these are in addition to the environment variables defined by the common Environment Setup Script. The Includes group defines overrides for any of the wrapper configuration settings defined in the main configuration. Typically, you never have to touch anything in any of these Java Service Wrapper configuration groups since the defaults should work everywhere. However, there are times when you might have to turn on some additional debug configuration settings or pass in new/modified VM options to the agent VM. In those cases, this configuration is where you would put those things for those agents running on Windows as a Windows Service.

Agent Launcher Script (UNIX-only)

If the agent is running on UNIX, the agent will have a child service that controls the agent if it is running as a background daemon process. There is no additional configuration for this service - this launcher script is configured by the Environment Setup Script.

Rebooting the Agent and its Java VM

There may be times when you would like to recycle the internal components of the agent, but not take down the entire agent VM process. However, other times, you may wish to reboot the entire agent, including the Java virtual machine. This section describes why you would want to do these things and how to do them.

Restart Internal Agent Components

The main internal agent component is called the "Plugin Container". It loads all agent plugins and manages the lifecycle of all the plugins it loads. If you want to restart that internal plugin container (for debugging purposes, or to re-initialize all plugins to get them to start over, as if just booting up), you can execute the operation called "Restart Plugin Container" located in the Operations tab of the main agent server resource. If you want to completely restart all internal components of the agent but not completely reboot the Java virtual machine, you can execute the operation called "Restart". This is useful, for example, if you want to reboot the internal communications subsystem (note that restarting the agent in this manner will also restart the plugin container as well).

In either case described above, the original agent Java virtual machine remains intact. That is to say, the Java virtual machine process never exited - it remained running. The operating system will still see the agent as the same process as it did before, with the same process ID. The agent's VM never changed its heap or non-heap allocations and the original VM options that were set when the agent was first started remain in effect.

Restart Agent Java VM

But what if you wanted to completely kill the agent JVM and restart it? You normally want to do this if you changed the launcher environment configuration in such a way that would affect the agent VM and you need the VM to restart to pick up those changes (e.g. if you want to add a new or different -Xmx heap memory setting for the agent).

You can do this by going to the Operations tab of the agent server's child service that corresponds to the agent launcher. On Windows, this is the Agent Java Service Wrapper Launcher service; on UNIX, this is the Agent Launcher Script service. Both of those resources provide an operation called "Restart" that shuts down the agent process and restarts it. This will effectively kill the original agent VM process and then ask the operating system to restart another one.

To configure the agent VM's settings, you would edit the configuration found in the Configuration tab of the "Environment Setup Script" child service.