Event Broker/Monitor (BEA Tuxedo Systems)

 

The BEA Tuxedo Event Broker/Monitor is a tool that enhances the tracking of events in a running application.

This topic includes the following topics:

• Events

• Setting Up Event Detection

• Subscribing to Events

• Application-specific Event Broker/Monitors

• How an Event Broker/Monitor Might Be Deployed

• How the Event Broker/Monitor Works

  Note: This chapter is specific to the BEA Tuxedo system. However, BEA WebLogic Enterprise administrators should know that each BEA WebLogic Enterprise application relies on the BEA Tuxedo System Event Broker. This event broker must be started before any servers providing the NameManager service in a BEA WebLogic Enterprise application's UBBCONFIG file are started. For details, see the section "Required Order in Which to Boot Servers (WLE Servers)" in Creating a Configuration File.

The BEA Tuxedo Event Broker/Monitor extends the usefulness of the USERLOG (in which the BEA Tuxedo system records system events) by providing the following:

• A system-wide summary of events

• A tool that lets you set up various types of automatic notification when certain events occur

The BEA Tuxedo Event Broker/Monitor is built on the AdminAPI, the administrative programming interface to the BEA Tuxedo system. It is an example of administration through programming.

Note: This chapter demonstrates how you can use the BEA Tuxedo AdminAPI to enhance your application. For an actual example that you can run as a demo and copy from, see the bankapp application (distributed with the BEA Tuxedo system) and the BEA Tuxedo Application Development Guide.

 

---

Events

An event is a change in a component of a running application. This change may be harmless or it may cause a problem that requires work by the operator or administrator (and, in some cases, particular software) to be resolved.

Event Classifications

The BEA Tuxedo Event Monitor keeps track of events in a running application and classifies them on the basis of severity. The Event Monitor uses the same three severity classifications used by the BEA Tuxedo system to sort system messages sent to the USERLOG: information (INFO), warnings (WARN), and errors (ERROR).

• An INFO event is one of the following:

  • A state change of a process

  • The detection of a configuration change

• A WARN event is a configuration change that threatens the performance of the application.

• An ERROR event is an abnormal occurrence, such as:

  • A server dying

  • A network connection being dropped

List of Events

Events affecting objects in the classes defined in TM_MIB(5) are tracked. The list is published in the EVENTS(5) reference page in the BEA Tuxedo Reference Manual on the online documenatation CD.

The designers of an Event Broker/Monitor need to decide which events to track. Users of the system need to know the list of events being tracked.

 

---

Setting Up Event Detection

You can set the BEA Tuxedo system event detection logic to do two things:

• Post messages to a UNIX error message log (syslogd)

• Post events to the BEA Tuxedo event server

To activate event detection logic, set and export TMSYSLOGD_FACILITY to a numeric value from 0 to 7.

For details, see syslogd(3c) in a UNIX system reference manual.

 

---

Subscribing to Events

Clients subscribe to events by calls to tpsubscribe(3c). A call to tpsubscribe has a required argument, eventexpr, that points to a wildcard string. This string, in turn, identifies the events about which the user wants to know. The wildcard string makes use of the syntax described in recomp(3c) to apply the subscription to more than one type of event. The wildcard string is used to match the message distributed when the event is detected.

In the BEA Tuxedo System Monitor, the message includes the severity level, so a user can subscribe accordingly. For example:

• A user who wants to be notified of all events related to BEA Tuxedo networking sets the value of eventexpr to the following:

  \.SysNetwork.*

• A user who wants to subscribe to all events with a severity level of ERROR sets the value of eventexpr to the following:

  \.*(ERR|err)\.*

When a client leaves an application (by calling tpterm) all of its subscriptions are "canceled." If the client later rejoins the application and wants those subscriptions, it must subscribe again. A well-behaved client unsubscribes before calling tpterm. A client that accepts notification via unsolicited messages should issue a tpunsubscribe(3c) call before leaving the application.

Another argument of the tpsubscribe call (in addition to eventexpr) is a pointer to a structure of type TPEVCTL (defined in atmi.h). Through the use of the TPEVCTL structure (or non-use, if the argument is NULL), the user can select the notification method to be used for sending information about subscribed events. If the argument is NULL, the Event Broker sends an unsolicited message to the subscriber. The subscriber can alternatively elect to have the notification sent to a service or to a queue in stable storage. If a client wants to enter such a subscription, it must invoke a service routine to subscribe on its behalf.

As a BEA Tuxedo system administrator, you can enter subscription requests on behalf of a client or server process through calls to the EVENT_MIB(5). You may also use two notification methods that are specified in entries in the EVENT_MIB (besides the three available in tpsubscribe):

• A command can be invoked via the UNIX system(2) command.

• A message can be sent to the userlog.

 

---

Application-specific Event Broker/Monitors

By "application-specific Event Broker/Monitor" we mean a monitor customized to recognize events generated by application code. For example, a stock brokerage system could be programmed to post an event when a stock trades at or above a certain price. A banking application might be programmed to post an event when a withdrawal or deposit above a specified amount is detected.

The function of an application-specific Event Broker/Monitor is similar to that of the BEA Tuxedo System Event Broker/Monitor: when an event is posted, subscribers are notified (or an action specified by the subscriber is initiated). This section describes the same three areas that were described above, pointing out how the customized monitor resembles and differs from the BEA Tuxedo system monitor.

Events

The real distinction between a BEA Tuxedo System Event Broker/Monitor and an Event Broker/Monitor for a specific application is the way events are defined. System events are defined in advance by the BEA Tuxedo system code. For an application, designers must select application events to monitor. Application programs must be written to a) detect when an event of interest has occurred, and b) post the event to the Event Monitor via tppost.

Event List

There is no difference between the Event Lists generated and used on an application-specific Event Broker/Monitor and a BEA Tuxedo System Event Broker/Monitor. The BEA Tuxedo System Event Broker/Monitor makes a list of monitored events available to interested users. (For details, see the EVENTS(5) reference page in the BEA Tuxedo Reference Manual.) In the same way, when an application-specific Event Broker/Monitor is being used, interested users should have access to a list of monitored events. The names of system events begin with a dot ( . ); application-specific event names may not begin with a dot ( . ).

Subscriptions

The process of subscribing to an event in an application-specific Event Monitor is the same as that of subscribing with the BEA Tuxedo system Event Monitor. Subscriptions are made by calls to tpsubscribe using the published list of events, so the application can identify the events to which you are subscribing.

Note: For the BEA Tuxedo System Event Monitor, EVENTS(5) lists the notification message generated by an event, as well as the event name. The event name is used as an argument when tppost is called. Subscribers, on the other hand, can take advantage of the wildcard capability of regular expressions to make a single call to tpsubscribe to cover a whole category of events. We strongly recommend using the same format for the published event list for an application-specific Event Monitor/Broker.

 

---

How an Event Broker/Monitor Might Be Deployed

The client interfaces with the Event Broker/Monitor through either of two servers provided by the BEA Tuxedo system:

• TMSYSEVT(5)

• TMUSREVT(5)

These servers introduce the concept of a principal server and zero or more secondary servers. Both types (principal and secondary) process events and trigger notification actions.

To install the BEA Tuxedo system Event Broker/Monitor, configure:

• The principal server on the MASTER site

• Whatever secondary servers your installation might need on other machines on your network

With an application-specific Event Broker/Monitor, the primary server may be on any machine other than the MASTER; secondary servers may be located around your network.

The reason for locating secondary servers on other nodes of your network is to reduce the amount of network traffic caused by posting events and by distributing event notifications to subscribers. The secondary server periodically polls the primary server to get the latest version of the subscription list, which stores filtering and notification rules.

You can configure the polling interval as needed. There may be a perception that event messages are lost during this period between the time at which subscriptions are initially added and the time at which all secondary servers are updated. If the application cannot "lose" messages, the programs must wait, at least until the end of the polling period, before tppost is called for the new event.

 

---

How the Event Broker/Monitor Works

The BEA Tuxedo Event Broker/Monitor is built with the following AdminAPI components:

• ATMI Extensions-the Event Monitor uses three function calls in the ATMI library:

  • tppost

  • tpsubscribe

  • tpunsubscribe

    These three functions appear in both the C library and the COBOL library. (For details, see Sections (3c) and (3cbl) in the BEA Tuxedo Reference Manual.

• MIB component-the EVENT_MIB management information base is the control file in which you can store subscription information and filtering rules. In your own application, you cannot define new events for the BEA Tuxedo system Event Broker/Monitor, but you can customize the Event Broker/Monitor to do the following:

  • Track events

  • Distribute notifications of special interest to the application