Structure

The TIBCO Hawk Console API is partitioned along the functional lines of monitoring and management. At the root is the TIBHawkConsole class from which you can access the AgentMonitor and AgentManager, which encompass the monitoring and management facilities of the API.

The TIBCO Hawk Console API allows you to monitor all agents simultaneously from a single program.

For each agent, the APIs monitoring capabilities can be decomposed into four areas:

All monitoring is performed using event notification. Listeners are registered with the AgentMonitor for the type of monitoring required and the relevant status messages are delivered as events when they are detected.

A registered listener for a particular type of event will receive notifications for all monitored agents that generate that event. For example, registering a AgentMonitorEventLister with the console will allow it to receive AgentMonitorEvents for all agents known to the console, thus allowing it to track the alive or expired status of every agent.

The most basic type of monitoring is the monitoring of agent existence. This is achieved by registering an AgentMonitorListener with the AgentMonitor. When you register an AgentMonitorListener, it will receive one agent-alive event for every agent the console can detect.

An agent-alive event is actually represented by the delivery of an AgentMonitorEvent to the onAgentAlive() method of the listener. This event contains a reference to an AgentInstance object which identifies which agent it pertains to. As new agents appear in the network, new agent-alive events will be generated to identify them. When the console is no longer able to communicate with an agent, it will issue an agent-expired event for that agent. This is performed by delivering a AgentMonitorEvent to the onAgentExpired() method of the listener. As before, this event contains a reference to an AgentInstance object which identifies which agent it pertains to. The console can lose communication with an agent for several reasons, for example if the agent process is no longer running, the machine it was running on has crashed, or because of a problem in the underlying communications infrastructure such as a network outage.

Each agent contains a collection of objects called microagents. Microagents have methods through which monitoring and management is performed. Microagents represent managed entities such as the operating system's subsystems, log files, event logs, or applications. A newly launched application instrumented with AMI will dynamically appear as a microagent on its managing agent (by default, the one located on the same processor). When the instrumented application terminates, the corresponding microagent will also be removed.

Microagent list monitoring is used to track the dynamic list of microagents in an agent. Events are delivered when microagents are added and removed.

To perform this type of monitoring you simply register a MicroAgentListMonitorListener with the AgentMonitor. Events of type MicroAgentListMonitorEvent are then delivered to either the onMicroAgentAdded() or onMicroAgentRemoved() method of the listener. The event contains an AgentInstance object, which identifies the agent, and a MicroAgentID object, which identifies the microagent.

Rulebases direct the monitoring activities of an agent. Each rulebase is a collection of rules which are usually grouped together to monitor an application or system resource. An agent may have more than one loaded rulebase and this list can change dynamically.

Rulebase list monitoring is structurally similar to microagent list monitoring. It is used to monitor the dynamically changing list of rulebases that are loaded on an agent.

To perform this type of monitoring you register a RuleBaseListMonitorListener or onRulebaseUpdated with the AgentMonitor. Events of type RuleBaseListMonitorEvent are then delivered to either the onRuleBaseAdded() or onRuleBaseRemoved() method of the listener. The event contains an AgentInstance object, which identifies the agent, and a RuleBaseStatus object, which is used to identify the rulebase being added or removed.

The onRulebaseUpdated() listener provides an atomic update callback for rulebase update events. To receive onRulebaseUpdated(), implement ExtendedRuleBaseListMonitorListener as per the definition provided in API Reference section.

One of the actions a rulebase can take is to generate an alert, which is usually done to signal that a problem condition has been detected. Alerts contain a state, to indicate the problem severity, and text, which provides the problem description. If the alert condition, as defined by the rulebase, ceases to exist, the rulebase will generate a clear against that alert.

Every alert is associated with a particular rulebase and every rulebase is associated with a particular agent. (Technically, rulebases are said to be associated with the RuleBaseEngine microagent instance registered with that agent, therefore the association with the agent is indirect.) The alert state of a rulebase will always be highest alert state of all the active (non-cleared) alerts associated with it. The alert state of an agent (or its RuleBaseEngine microagent) is the highest alert state of any of its currently loaded rulebases. Therefore, alerts and clears can potentially change the state of the rulebase and agent that generated them.

Alert monitoring is performed by registering an AlertMonitorListener with the AgentMonitor. Alerts and clears generated by an agent are detected by the console and delivered as AlertMonitorEvent objects to the listener. Since AlertMonitorEvent is an abstract class, one of its concrete subclasses is delivered: PostAlertEvent for alerts and ClearAlertEvent for clears.

Every AlertMonitorEvent contains flags that indicate whether it caused a change in the state of the RuleBaseEngine or the rulebase it is associated with. It also holds the current states of those objects after taking into account the current event. Other attributes include an alert ID, which uniquely identifies an alert, and the time the event was generated.

Because AlertMonitorEvent extends AgentMonitorEvent, it also has an AgentInstance attribute to identify the agent that generated the event.

The PostAlertEvent class extends AlertMonitorEvent and adds the state of the alert and the alert text. The ClearAlertEvent class extends AlertMonitorEvent and adds the reason-cleared text. This string identifies the reason the alert was cleared.

All alert states are represented as integer values that are mapped using the AlertState interface. A PostAlertEvent with a state of AlertState.NO_ALERT is also called a notification.

Common to all monitoring events, and that which relates them to each other, is the agent instance they pertain to. This agent instance is represented in the TIBCO Hawk Console API by the AgentInstance class. The following definitions and discussion describe this class, the related AgentID class, and their role in monitoring.

The agent ID specifies the attributes of an agent process that are used to uniquely identify it. These attributes are

The agent instance is an instantiation of a agent; the actual agent process running on some machine in the network. If an agent is restarted, the new process represents a new agent instance. Agent instances have a life span that begins with the starting of an agent process and ends with its termination. Agent instances are represented by the AgentInstance class.

In order for the TIBCO Hawk system to function correctly, every concurrently running agent instance must have a unique agent ID. The console will attempt to detect violations of this condition and produce a warning. However, this may not be detectable in all circumstances and so the system administrator must insure that every agent has a unique agent ID.

If a console client is interested in tracking agent status across agent instances or console agent instances then it may do so using the console agent ID, that is, the AgentID class. If a agent is restarted several times (without changing its ID attributes) then this will result in the creation of several distinct instances of AgentInstance in the console. These different instances, however, will all have equal AgentID values to reflect the fact that they all relate to the same logical agent. Note that these multiple instances of AgentInstance will never be referenced simultaneously by the console. This is because the console will never hold two AgentInstance objects with equal AgentID attributes at any one time.

Management functions are performed by invoking management operations on microagents. As described in Microagent List Monitoring, each agent contains a collection of objects called microagents. Microagents have methods through which all monitoring and management is performed. Microagents represent managed entities such as the operating system's subsystems, log files, event logs, applications, and even the agent itself.

The AgentManager class is used to interact with microagents. An instance of this class is obtained by invoking the getAgentManager() method of the TIBHawkConsole class.

The first step in interacting with a microagent is to obtain its descriptor. This descriptor enumerates the available methods and describes their signature and their return types. With this information you can then invoke methods and subscribe to method results for an individual microagent. You can also perform a group operation that simultaneously performs a method invocation on multiple instances of the same microagent across multiple agents.

Descriptors are represented by the MicroAgentDescriptor class. They are obtained by invoking the describe() method of the AgentManager class. A MicroAgentDescriptor fully describes a microagent. It contains a list of MethodDescriptor objects that describe each available method and all that is needed to invoke them.

The methods of a microagent are divided into three categories depending on their impact. These categories are enumerated by the following static variables of the MethodDescriptor class:

The describe() method of the AgentManager requires an argument of type MicroAgentID. There are two general ways to obtain MicroAgentID objects:

•

If your application is also performing monitoring then the MicroAgentIDs for microagents loaded on a particular agent can be obtained from the method AgentInstance.getStatusMicroAgents(). A registered MicroAgentListMonitor object also receives MicroAgentIDs in the events delivered to it.

•

The method AgentManager.getMicroAgentID() can also be used to obtain MicroAgentID objects. It takes a microagent name as its argument and returns an array of all microagents of that name that are currently loaded on all agents the console can communicate with. This method blocks for a period of time while it queries the agents on the network. A second version of this method accepts an integer that indicates the minimum number of desired microagent ids in the return. This method generally returns more quickly than the first version if the minimum number specified is less than or equal to the actual number of matching microagents on the network.

Microagent methods are invoked using the invoke() method of the AgentManager. This method takes a MicroAgentID and a MethodInvocation object. The MicroAgentID may be obtained as described in Microagent Descriptors. The MethodInvocation can be constructed using the data provided in the microagent descriptor.

Method invocations return an instance of the MicroAgentData class, which acts as a container for transmitting invocation results. MicroAgentData objects contain source and data attributes. The source attribute is a MicroAgentID object identifying the source of the data. The data attribute contains the actual method invocation results.

Two general types of errors can occur with method invocations:

Thus, a successful method invocation is one that doesn't throw an exception and does not deliver a MicroAgentException in the data field of its MicroAgentData return.

If the method invocation is successful, the data field of its MicroAgentData return will contain the method's return value or null if the method doesn't return a value.

The AgentManager also allows you to register a subscription for microagent methods with its subscribe() method. Registering for a subscription is analogous to registering for an event. It results in a continuous stream of MicroAgentData return values from the method being subscribed to. This data is asynchronously delivered to a SubscriptionHandler object supplied during registration.

In addition to a SubscriptionHandler, the subscribe() method of AgentManager requires a MicroAgentID, to identify the target, and a MethodSubscription object.

The MethodSubscription class extends the MethodInvocation class. A MethodSubscription should be constructed in accordance with the MethodDescriptor of the target method.

Registering a subscription returns a Subscription object that can be used to cancel the subscription and to examine how the subscription was created

Only methods that return data should be subscribed to. This includes methods of type IMPACT_INFO and IMPACT_ACTION_INFO.

You can use either of two constructors to build a MethodSubscription, depending on whether you are creating a subscription for a synchronous or asynchronous method. The MethodDescriptor for a method indicates whether the method is synchronous or asynchronous. An asynchronous method is analogous to an event source. Listeners that subscribe to an asynchronous method will receive the method's declared return value each time a particular event occurs.

The MethodSubscription constructor for synchronous method subscriptions requires an interval parameter. It is used to specify a desired subscription service rate. Subscriptions made of synchronous methods will use this value as a hint to determine how often to deliver data to service a subscription. Most microagents will usually enforce a minimum rate, which will be used if the supplied value is below their minimum.

The MethodSubscription constructor for asynchronous method subscriptions does not accept an interval parameter. Asynchronous methods deliver data at a rate determined by the microagent, typically, whenever it is available.

Two general types of errors can occur with subscriptions:

Group operations are performed with the groupOp() method of the AgentManager. They are very similar to method invocations. The difference is that they require an array of MicroAgentID targets and return an array of MicroAgentData values.

A group operation effectively performs a method invocation simultaneously on all of the specified target microagents. It is useful for affecting a group of microagents in a single operation.

By default, the console monitors and can communicate with every agent in a given TIBCO Hawk domain. If, however, you are building an application that needs to interact with only a single agent, you can initialize the console in such a way that limits its communication to just that agent. This results in a lightweight console instance that uses fewer resources.

Instantiating a lightweight console involves constructing a TIBHawkConsole object with a fully qualified hawkDomain parameter. A fully qualified hawkDomain narrows down the domain to a single agent and contains the three parts that uniquely identify an agent, in a dot-separated format:

•

<hawkDomain> is what would be used as the hawkDomain parameter of the TIBHawkConsole constructor if you were instantiating a console that communicates with all agents. If an agent is configured without a hawkDomain specification, it uses the value "default".

•

<agentDNS> should match the agentDNS (also called agent domain) parameter with which the agent was configured. If the agent was not configured with an agentDNS, it uses the value "none".

None of the three elements may contain the dot '.' character. The dot is used as a separator in a fully qualified hawkDomain. If any of the three components require a dot (agentDNS typically does), replace all occurrences with the underscore '_' character. The agent automatically performs this translation on its end.

For example, if an agent is configured with the following values:

the fully qualified hawk domain is:

To build a console application with secure domain, you need to use a secure transport. You can connect to TIBCO EMS transport with SSL using Console API for Agent-Console communication.

Refer to HAWK_HOME/examples/console_api/TestConsoleSSL.java for a sample java program to demonstrate a console test application which uses SSL parameters to connect to SSL.

The COM.TIBCO.hawk.agent.nest package is used to write TIBCO Hawk microagents that run inside the agent. To run as a microagent in the TIBCO Hawk agent, an object must implement either the MicroAgent or ServiceMicroAgent interface. Note that this package is dependent on the COM.TIBCO.hawk.console.talon package.