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

It is currently not possible to ignore a resource until the platform has at least one committed resource beneath it (thus implicitly commits the platform itself). It doesn't make sense to ignore the platform, because then what was the point of installing an agent on that box in the first place? If you ignore the platform, then you are ignoring all of the children servers and services beneath it, so you might as well just not install the agent on that box at all. Thus, for each new agent in the system, just make sure you commit at least one resource; then you can ignore any and all other resources under that platform.

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-discover some resource in your enterprise, you may still have the option of manually adding it to inventory. This is determined by whether it is a type of resource that includes support for being manually added.

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.

It is illegal to manually discover a resource unless the plugin can successfully connect to the resource given the properties that you were asked to specify, so the resource should have a green availability icon next to it (meaning that it's UP).

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 Inventory quick navigation icon in the Browse Resources page (the icon is a clipboard). The Inventory tab has three subtabs - Overview, Connection, and Agent. When you first go to the Inventory tab, the Overview subtab will be selected by default.

Overview Subtab

This page is split into a few sections:

General Properties

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

Groups Containing this Resource

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.

Connection Subtab

The Connection subtab allows you to edit the Resource's connection properties. Connection properties tell Agent plugin associated with the Resource how to connect to the underlying managed resource. For example, here is the Connection subtab for a JBossAS Server Resource:

The Naming Provider URL is the URL the jboss-as plugin will use to connect to the managed JBossAS instance in order to retrieve JMX attributes and invoke JMX operations.

To edit the properties, click the EDIT... button.

Notice that most of the properties are now editable. The JBoss HOME Directory and Configuration Path properties are not editable, because those properties are read-only; their values were automatically set by the Agent plugin associated with the Resource at the time the Resource was first discovered. Click the SAVE button to save the connection properties. Note, the Agent associated with the Resource must be running in order to successfully save the connection properties. To discard any changes you have made and return to the view-only mode, click the CANCEL button.

To view the history of revisions made to the Resource's connection properties, click the HISTORY... button.

To view a particular revision, click the version number link in that revision's Version column.

Notice the details about the revision are displayed at the top of the page, and the connection properties themselves for the revision are displayed at the bottom of the page. Also notice the version number in the selected revision's Version column is suffixed with "* (selected)".

To delete one or more revisions from the history, check the checkboxes for those revisions, then click the DELETE SELECTED button.

To return to the current connection properties, click the < Return to Current Connection Properties link.

Agent Subtab

The Agent subtab 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 aren't receiving any metric data for the Resource.

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