Search

6. Agent Advanced Management Plug-in System (AMPS) Reference

download PDF
This is a reference of common components and elements used to write agent plug-ins.

6.1. Domain Objects

Domain objects include the basic pieces of the management inventory that define resources and types.

6.1.1. Resource and ResourceType

A Resource represents a single entity in inventory, be it a platform, server or service. The precise semantics of platforms, servers, adn services is vague, so a Resource object encapsulates any resource no matter what its category.
ResourceCategory is an enumeration that is associated with each Resource and indicates if the Resource is considered a platform, server, or service.
ResourceType represents types of resource instances that can be added to inventory. ResourceTypes are defined by plug-in descriptors. Another way of looking at it is that a ResourceType defines an application or service that can be managed by JBoss ON. ResourceTypes are added to JBoss ON as agent plug-ins are deployed, so a JBoss AS plug-in allows you to manage JBoss servers, a Tomcat plug-in manages Tomcat servers, and a custom plug-in can manage a custom application.

6.2. Plug-in Facets

A facet is simply an optional piece of functionality that a plug-in writer chooses to expose to the plug-in container and ultimately to the JBoss ON system as a whole. A plug-in writer is free to have his resource components implement some, all or none of these facets (obviously, the more facets that are implemented and exposed, the more powerful and useful the plug-in becomes).

6.2.1. AvailabilityFacet

This facet provides basic availability checking - is a managed resource up or down? When the plug-in container needs to know if a resource is running or not, it will ask the resource component's availability facet. Unlike the other facets, the AvailabilityFacet is required to be implemented by all resource components. You are forced to implement it because the ResourceComponent interface extends the AvailabilityFacet. You can optionally use the asynchronous availability collector to perform the avail checking.

6.2.2. ConfigurationFacet

This facet provides the ability for a resource component to modify the configuration of the actual managed resource. When a resource component implements this facet, it is saying it has the capability to get the current configuration of the managed resource as well as be able to change it. As an example, the JBoss AS Data Source Service resource component implements the ConfigurationFacet because it can report back to the user what the current settings are of that data source (e.g. its JDBC driver, its JNDI name, its connection pool size, etc) and it can allow the user to change those settings.

6.2.3. ContentFacet

Resources may have content associated with them including deployed software or software parts and other content. This system can be used to inventory these software parts and to install and remove them. Examples of deployed content are RPMs on Linux, EARs and WAR applications or libraries and deployment files on JBoss Application Server. Plug-ins can support arbitrary types of content with this system
Resources may have additional files (aka "content") associated with it - configuration files, deployment files, etc. Those resources that have associated content can implement the ContentFacet to help create, delete and manage that content.

6.2.4. ManualAddFacet

This facet should be implemented by the ResourceDiscoveryComponent class for types of resources that can be manually added to inventory via the JBoss ON GUI. In addition, the corresponding server or service elements in the plug-in descriptor must include the supportsManualAdd="true" attribute. Manual add can be a useful capability when a particular Resource cannot be auto-discovered for some reason.

6.2.5. MeasurementFacet

This facet exposes the capability for the component to collect measurement data from the managed resource and to report that data back to the server. For a measurement facet to work, the plug-in must define one or more metric definitions for the resource component's resource type in the plug-in descriptor. The resource component does not have to concern itself with how to schedule measurement collections and when it should collect the data. The only thing the MeasurementFacet requires the resource component to do is go out to the actual managed resource and collect the requested data. The plug-in container will manage all measurement collection schedules and will only call into the resource component's MeasurementFacet when the time is appropriate and it will only ask for the metrics that need to be collected at that time.
The measurement facet is what provides the graphs of measurement data that you see in the JBoss ON GUI Console.

6.2.6. OperationFacet

This facet allows the resource component to perform operations (aka control actions) on the managed resource itself. This allows, for example, the JBoss AS Server resource component to provide the capability to start and stop the JBoss AS server. Other examples of operations are being able to clear a connection pool for a data source, or ask a resource to empty a data cache. Whatever the managed resource can be told to do, a resource component can expose that as an operation to the JBoss ON user.

6.2.7. ResourceFactoryFacet

Some resource components can support the creation and deletion of child resources (for example, a resource component representing the JBoss AS server can create and delete JBoss AS data source services by creating and deleting *-ds.xml files). This facet exposes this functionality.

6.2.8. SupportFacet

To support managed resources, there is some data that support organizations might wish to know about regarding a managed resource, such as the contents of its log files, data files, and configuration files. The SupportFacet will provide a hook into this "support and maintenance" view of the managed resource.

6.3. Plug-in Components

6.3.1. ResourceDiscoveryComponent

The discovery component is an implementation written by the plug-in writer that performs the discovery of the actual managed resources. The discovery component's job is to scan the platform (that is, the machine the agent/plug-in container/plug-in is running on) and to report back what it finds. A discovery component is only responsible for finding resources that it directly is in charge of managing. That is to say, a JBoss AS plug-in discovery component is not responsible for discovering all Apache Web Servers - it only needs to find JBoss AS resources (leave the discovery of Apache Web Servers to the Apache plug-in).
A discovery component will be told to go hunt for resources at an appropriate time by the plug-in container. When the plug-in container asks the discovery component to go discover more resources, it will send in a ResourceDiscoveryContext object to the discovery component. This context contains all the information the component needs to perform its duties of finding and creating new resources. The discovery context is also used to inject resources into the discovery component, in the case where the plug-in container was able to discover new resources on behalf of the discovery component. A plug-in container can only auto-discover resources if the appropriate metadata is supplied to it via the plug-in's descriptor.

6.3.2. ResourceComponent

A resource component is a plug-in abstraction that represents an actual managed resource. A resource component is stateful whose lifecycle is managed by the plug-in container.
The plug-in container will start and stop a resource component at the appropriate times. When a resource component is started, it typically connects to its underlying resource (the managed resource it represents) and maintains that connection until it is stopped by the plug-in container (this is an implementation detail that a plug-in writer is free to change). A resource component implementation provides a way for the plug-in container to ask for the availability of the managed resource ("is this resource up? or has it gone down?") and to access optional functionality facets that a plug-in writer chooses to expose. More on facets below.

6.4. Native System Information Access

All plug-ins have access to a set of native libraries that allow plug-in components to ask the underlying operating system for details about the machine on which the plug-in is running. Some of these features are not available on all hardware and OS platforms - only those platforms that have the native libraries available will be able to support all features described below. However, for those platforms that do not have the native libraries available, there will still be a limited feature set available.

6.4.1. SystemInfoFactory and SystemInfo

The plug-ins will have access to a SystemInfo object that is specific to the hardware/OS platform on which the plug-in is running. Once a plug-in obtains a SystemInfo object from its context (either ResourceDiscoveryContext or ResourceContext), it can make calls to that object which will call down into the native libraries to obtain the requested data from the operating system. If there are no native libraries available, the SystemInfo will be backed with a pure Java implementation of some, but not all, of the methods defined in the SystemInfo interface (see the JavaSystemInfo implementation of that interface). The methods that are not supported by the pure Java implementation will throw an UnsupportedOperationException.

6.4.2. ProcessInfoQuery

One interesting feature the SystemInfo interface provides is the ability to probe the operating system's process table. This is useful for your ResourceDiscoveryComponent implementations because they can scan the list of running processes and try to determine if it can auto-detect a managed resource that it is tasked to discover.
Through the use of the ProcessInfoQuery object, you can find processes that match a given set of criteria, defined by the Process Info Query Language (PIQL). You can even set pre-defined PIQL queries in your plug-in's descriptor via the process-scan tag to have the plug-in container scan the process table on behalf of your plug-in.

Note

Rather than repeat already documented information, refer to ProcessInfoQuery http://git.fedorahosted.org/git/rhq/rhq.git?p=rhq/rhq.git;a=blob;hb=master;f=modules/core/native-system/src/main/java/org/rhq/core/system/pquery/ProcessInfoQuery.java to learn more about the syntax and usage of PIQL.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.