Monitoring Server Events


The TIBCO Enterprise Message Service server can publish topic messages for several system events. For example, the server can publish a message when users connect or disconnect. System event messages contain detail about the event stored in properties of the message. This section gives an overview of the monitoring facilities provided by the server. For a list of monitor topics and a description of the message properties for each topic, see Appendix C, Monitor Messages.

System Monitor Topics

The TIBCO Enterprise Message Service server can publish messages to various topics when certain events occur. There are several types of event classes, each class groups a set of related events. For example, some event classes are connection, admin, and route. Each event class is further subdivided into the events for each class. For example, the connection class has two events: connect and disconnect. These event classes are used to group the system events into meaningful categories.

All system event topic names begin with $sys.monitor. The remainder of the name is the event class followed by the event. For example, the server publishes a message to the topic $sys.monitor.connection.disconnect whenever a client disconnects from the server. The naming scheme for system event topics allows you to create wildcard subscriptions for all events of a certain class. For example, to receive messages whenever clients connect or disconnect, you would create a topic subscriber for the topic $sys.monitor.connection.*.

Monitor topics are created and maintained by the server. There is no need to explicitly create monitor topics in the configuration files or using the administration tool or API.

Monitoring Messages

You can monitor messages processed by a destination as they are sent, received, or acknowledged. The $sys.monitor topic for monitoring messages has the following format:

$sys.monitor.<D>.<E>.<destinationName> 

Where D is the type of destination, E is the event you wish to monitor, and destinationName is the name of the destination whose messages you wish to monitor. Table 36 describes the possible values of D and E in message monitoring topics.

Table 36 Message monitoring qualifiers (Sheet 1 of 2)
Qualifier
Value
Description
D
T
Destination to monitor is a topic. Include the message body in the monitor message as a byte array. Use the createFromBytes() method when viewing the monitor message to recreate the message body, if desired.
t
Destination to monitor is a topic. Do not include the message body in the monitor message.
Q
Destination to monitor is a queue. Include the message body in the monitor message as a byte array. Use the createFromBytes() method when viewing the monitor message to recreate the message body, if desired.
q
Destination to monitor is a queue. Do not include the message body in the monitor message.
E
s
Monitor message is generated when a message is sent by the server to:
  • a consumer
  • a route
  • an external system by way of a transport
r
Monitor message is generated when a message is received by the specified destination. This occurs when the message is:
  • Sent by a producer
  • Sent by a route
  • Forwarded from another destination by way of a bridge
  • Imported from transport to an external system
a
Monitor message is generated when a message is acknowledged.
*
Monitor message is generated when a message is sent, received, or acknowledged for the specified destination.

For example, $sys.monitor.T.r.corp.News is the topic for monitoring any received messages to the topic named corp.News. The message body of any received message is included in monitor messages on this topic. The topic $sys.monitor.q.*.corp.* monitors all message events (send, receive, acknowledge) for all queues matching the name corp.*. The message body is not included in this topic’s messages.

The messages sent to this type of monitor topic include a description of the event, information about where the message came from (a producer, route, external system, and so on), and optionally the message body, depending upon the value of D. See Appendix C, Monitor Messages for a complete description of the properties available in monitoring messages.

You must explicitly subscribe to a message monitoring topic. That is, subscribing to $sys.monitor.> will subscribe to all topics beginning with $sys.monitor, but it does not subscribe you to any specific message monitoring topic such as $sys.monitor.T.*.foo.bar. You can, however, specify wildcards in the destinationName portion of the message monitoring topic to subscribe to the message monitoring topic for all matching destinations. For example, you can subscribe to $sys.monitor.T.r.> to monitor all messages received by all topics. For performance reasons, you may want to avoid subscribing to too many message monitoring topics. See Performance Implications of Monitor Topics for more information.

Viewing Monitor Topics

Monitor topics are just like any other topic. To view these topics, create a client application that subscribes to the desired topics.

Because monitor topics contain potentially sensitive system information, authentication and permissions are always checked when clients access a monitor topic. That is, even if authentication for the server is disabled, clients are not able to access monitor topics unless they have logged in with a valid username and password and the user has permission to view the desired topic.

The admin user and members of the $admin group have permission to perform any server action, including subscribing to monitor topics. All other users must be explicitly granted permission to view monitor topics before the user can successfully create subscribers for monitor topics. For example, if user BOB is not a member of the $admin group, and you wish to allow user BOB to monitor all connection events, you can grant BOB the required permission with the following command using the administration tool:

grant topic $sys.monitor.connection.* BOB subscribe 

Bob’s application can then create a topic subscriber for $sys.monitor.connect.* and view any connect or disconnect events.

Topics starting with $sys.monitor do not participate in any permission inheritance from parent topics other than those starting with $sys.monitor (that is, *.* or *.> is not a parent of $sys.monitor).
Therefore, granting permission to a user to subscribe to > does not allow that user to subscribe to $sys.monitor topics. You must explicitly grant users permission to $sys.monitor topics (or parent topics, such as $sys.monitor.admin.*) for a user to be able to subscribe to that topic.

Monitor topics publish messages of type MapMessage. Information about the event is stored within properties in the message. Each system event has different properties. Appendix C, Monitor Messages describes each of the monitor topics and the message properties for the messages published on that topic. Your application can receive and display all or part of a monitor message, just as it would handle any message sent to a topic.

Monitor messages are like any topic messages, so you can have any number of applications that subscribe to monitor messages. You can create different applications that subscribe to different monitor topics, or you can create one application that subscribes to all desired monitor topics. Your topic subscribers can also use message selectors to filter the monitor messages so your application receives only the messages it is interested in.

Performance Implications of Monitor Topics

The TIBCO Enterprise Message Service server only generates messages for monitor topics that currently have subscribers. So, if no applications subscribe to monitor topics, no monitor messages are generated. Generating a monitor message does consume system resources, and therefore you should consider what kinds of monitoring your environment requires. System performance is affected by the number of subscribers for monitor topics as well as the frequency of messages for those topics.

For development and testing systems, monitoring all system events is probably desirable. Usually, development and testing systems do not have large message volumes, and monitoring can give you information about system problems.

For production systems, monitoring all events may have an adverse effect on system performance. Therefore, you should not create topic subscribers for $sys.monitor.> in your production system. Also, monitor events are likely to be added in future releases, so the number of monitor topics may grow. Subscriptions to monitor topics in production systems should always be limited to specific monitor topics or wildcard subscriptions to specific classes of monitor topics that are required.

Also, consider the frequency of messages to each monitor topic. System administration events, such as creating topics, routes, and changing permissions, do not occur frequently, so creating subscriptions for these types of events will most likely not have a significant effect on performance.

Also, using message selectors to limit monitor messages can improve performance slightly. The server does not send any messages that do not match a subscriber’s message selector. Even though the message is not sent, the message is still generated. Therefore there is still system overhead for subscribers to a monitor topic, even if all messages for that topic do not match any subscriber’s message selector filter.


TIBCO Enterprise Message Service™ User’s Guide
Software Release 4.3, February 2006
Copyright © TIBCO Software Inc. All rights reserved
www.tibco.com