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.*.
The $sys.monitor topic for monitoring messages has the following format:
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 79 describes the possible values of
D and
E in message monitoring topics.
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.
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. However, if another subscriber generates interest in the message monitor topics, this subscriber will also receive those messages.
You can 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.
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:
Bob’s application can then create a topic subscriber for $sys.monitor.connect.* and view any connect or disconnect events.
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 A, 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. However, there are some ways in which monitor messages are handled differently from standard messages:
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.