Inventory

This page discusses RHQ's inventory - the set of resources that it knows about and works with.

Overview

The "inventory" is the term for the central repository that houses items RHQ manages and monitors. Before an item can take advantage of the feature set that RHQ provides, it must first be imported into the inventory.

Concepts

Resource Types

A resource type is defined on a per-plugin basis, but a single plugin may define multiple resource types. A resource type is a fairly generic concept that tries to identify and delineate a construct, whether that be an entire operating system, a program running in some operation system, or a tiny little service running inside that program. All resources have exactly one resource type, usually just referred to as its type.

Resource Category

As hinted above, there are three major categories that any resource type falls into: an operating system, a program, or a service. The vocabulary RHQ uses for these three groups is platform, server, and service, respectively. Each of these resource categories is discussed in more detail below in the context of how they are arranged hierarchically.

Resource Hierarchies

The resource hierarchy attempts to mimic, as closely as possible, how programs and processes are physically and/or programmatically structured on a platform. Below are the supported ways resources can be related by category.

Although a picture is worth a thousand words, below is a full text description for those that want to know precisely what this one says:

• A server can be a child of a platform (e.g. JBoss AS on Linux)
  • A platform can have many children servers
• A service can be a child of a server or a platform (e.g. JMS Queue on JBoss AS)
  • A platform can have many children services
  • A server can have many children services
• A server can be a child of another server (e.g. Tomcat embedded in JBoss AS)
  • A server can have many children servers
• A service can be a child of another service (e.g. Table inside a Database)
  • A service can have many children services

It's worth mentioning that a resource can only have one parent. Thus, the resource hierarchy we're dealing with in RHQ actually takes the form of a directed, acyclic graph (DAG). The graph's root is its platform, and the servers and services beneath it help to form a shallow, yet relatively wide tree.

Resources

Each resource is a concrete instance of one of the plugin-defined resource types. Thus, each resource will have exactly one resource type. Resources are the actual instances of the platforms, servers, and services that are installed on the boxes where the RHQ Agents reside.

Inventory states

Resources can be in the following states within RHQ

NEW

• most resources will be automatically discovered by RHQ
• the auto-discovery portlet on the dashboard will show discovered resources that have not yet been either ignored or imported (a.k.a committed)

IGNORED

• this state is used to "hide" one or more auto-discovered resources; instead of being imported into inventory, these resources can instead be "ignored"
• this feature is useful if the discovery process found servers that you're not interested in managing / monitoring at this time
• resources in this state will not show up in inventory nor in the auto-discovery portlet
  • to see resources that have previously been ignored (as well as to unignore them), click the "View All..." button of the auto-discovery portlet
• unignoring a resource will put it back into the NEW state
  • a resource must be unignored before it can be imported into inventory

COMMITTED

• resources that have been imported successfully are marked as committed
  • note: importing a resource will implicitly import (a.k.a commit) all of it's children resources recursively
• when using the resource browser, only committed resources will be shown

Controlling Inventory

Autodiscovery Portlet

The usual way of taking resources into inventory is by using the autodiscovery portlet. As soon as you connect a new RHQ Agent to the RHQ Server, it will send information about the platform and servers it discovers (usually via a process table scan). This scan is performed when the RHQ Agent first starts up, and then is done periodically to discover newly added resources in the system.

The discovered resources will be shown in the autodiscovery portlet on the Dashboard:

From there you can press the import button to commit the resource and take it into inventory. For each platform or server committed, it will trigger another type of scan which will search recursively for all nested servers and services.

The time it takes to find all of the nested resources beneath a parent resource may vary; it largely depends on the number of resources there are to be discovered. Each server or service scanned in this way will be automatically committed beneath its respective parent resource.

Autodiscovery queue

When you click on "View all..." you will be transferred to a list of all resources that are either new or ignored. This autodiscovery queue is useful when dealing with larger inventories, as the auto-discovery portlet doesn't wield very much screen real estate on the dashboard.

Here you can unignore resources or import any resources that are in new state.

Manual discovery

If for some reason it is not possible to auto-detect some resource in your enterprise, you still have the option of manually adding it to inventory.

To add a new resource, use the resource browser to find what should be its logical parent resource. Remember, since the resource browser only shows committed resources, you must first import the parent in order to manually add a child resource to the inventory.

Click over to the inventory tab of this parent resource. The drop-down labeled "Manually add..." is the first step towards bringing a resource into inventory manually; select the type of resource you want to add.

The next page will display all properties that the plugin requires (each resource type in the system has a different set of required properties) in order to be able to uniquely identify and successfully connect to this new resource.

After submitting the form, the resource will start in the committed state, and thus be available for viewing in the resource browser.

Now the resource is ready to be monitored and managed like any other auto discovered resource.

User Interface (Inventory Tab)

You can reach the inventory tab for a resource by clicking its 'I' icon in the Browse Resources page.

This page is split into a few sections:

General section

This section shows general information about the resource like when it was taken into inventory, last changed and its description.

Clicking the edit button lets you change the resources name, description and location field.

Child resources

This section shows the children of current resource with their availability. The quick link icons known from the Browse Resources page are available as well

Manually add child resources

Below the list of children you see the "Manually add" section referred to above in the Manual discovery section. This function serves to add child resources that were not autodiscovered.

The drop down will contain all resource types that can be manually added for this parent.
Selecting a type and clicking "OK" will lead to a template selection page:

Here you can select a template that fills in some default values. After that you are forwarded to a page where you can fill in the remaining values.
Please refer to Configuration#Property types to learn more about possible property types.

Create new child resources

Some resources also allow to create new children. This means that the new child resource will be created on the target resource as a new child. This way you can, for example, create a new JMS destination directly from your RHQ console. If the managed resource allows the creation of child resources, you will also see a "Create new" button.

As with manually adding a child resource, you will be forwarded to pages that are specific to the respective resource type.

Deleting resources

It is possible for some resource types to be physically deleted through RHQ. This is defined in the plugin descriptor of the plugin handling the resource.

If a resource can be deleted, it will show a checkbox in front of it:

Checking the box will enable the "Delete selected" button. When you press it, you will
be presented with a warning where you can cancel the action.

If you click on ok, a few things will happen:

• the resource will be removed from inventory (along with any metric history, operational history, etc)
  • all of its child resource will also be removed from inventory (along with all history too)
  • the resource and its children will be removed from any resource groups they are in
• the agent will delete the physical entity on the managed box

Group membership

This section shows the list of groups that this resource is part of.

In the example it is a compatible group named "Macs" with 1 member. The group availability is up (i.e. all members are up).

Clicking on the 'I' icon or on the group name will lead you to a page where you see the group members and more group-specific things. See Groups for more information.

Agent information

The last section on this page shows information about the agent that is managing this resource. This will help you debug cases where you, for example, set up everything correctly but you don't receive metric data for monitoring

The section lists the IP address of the agent along with the port the agent is listening on for commands from the server.