Sun Java System Message Queue 4.1 Administration Guide

Writing an Application to Monitor Brokers

Message Queue provides a metrics monitoring capability by which the broker can write metrics data into JMS messages, which it then sends to one of a number of metrics topic destinations, depending on the type of metrics information contained in the message.

You can access this metrics information by writing a client application that subscribes to the metrics topic destinations, consumes the messages in these destinations, and processes the metrics information contained in the messages.

There are five metrics topic destinations, whose names are shown in Table 10–6, along with the type of metrics messages delivered to each destination.

Table 10–6 Metrics Topic Destinations


Topic Name	Description
`mq.metrics.broker`	Broker metrics
`mq.metrics.jvm`	Java Virtual Machine metrics
`mq.metrics.destination_list`	List of destinations and their types
`mq.metrics.destination.queue.queueName`	Destination metrics for queue `queueName`
`mq.metrics.destination.topic.topicName`	Destination metrics for topic `topicName`

Setting Up Message-Based Monitoring

This section describes the procedure for using the message-based monitoring capability to gather metrics information. The procedure includes both client development and administration tasks.

To Set Up Message-based Monitoring

Write a metrics monitoring client.

See the Message Queue Developer’s Guide for Java Clients for instructions on programming clients that subscribe to metrics topic destinations, consume metrics messages, and extract the metrics data from these messages.

Configure the broker’s Metrics Message Producer by setting broker property values in the config.properties file:
1. Enable metrics message production.
  
  Set imq.metrics.topic.enabled=true
  
  The default value is true.
2. Set the interval (in seconds) at which metrics messages are generated.
  
  Set imq.metrics.topic.interval=interval .
  
  The default is 60 seconds.
3. Specify whether you want metrics messages to be persistent (that is, whether they will survive a broker failure).
  
  Set imq.metrics.topic.persist .
  
  The default is false.
4. Specify how long you want metrics messages to remain in their respective destinations before being deleted.
  
  Set imq.metrics.topic.timetolive .
  
  The default value is 300 seconds.

Set any access control you desire on metrics topic destinations.

See the discussion in Security and Access Considerations below.

Start up your metrics monitoring client.

When consumers subscribe to a metrics topic, the metrics topic destination will automatically be created. Once a metrics topic has been created, the broker’s metrics message producer will begin sending metrics messages to the metrics topic.

Security and Access Considerations

There are two reasons to restrict access to metrics topic destinations:

Metrics data might include sensitive information about a broker and its resources.
Excessive numbers of subscriptions to metrics topic destinations might increase broker overhead and negatively affect performance.

Because of these considerations, it is advisable to restrict access to metrics topic destinations.

Monitoring clients are subject to the same authentication and authorization control as any other client. Only users maintained in the Message Queue user repository are allowed to connect to the broker.

You can provide additional protections by restricting access to specific metrics topic destinations through an access control file, as described in User Authorization.

For example, the following entries in an accesscontrol.properties file will deny access to the mq.metrics.broker metrics topic to everyone except user1 and user 2.

topic.mq.metrics.broker.consume.deny.user=*
topic.mq.metrics.broker.consume.allow.user=user1,user2

The following entries will only allow users user3 to monitor topic t1.

topic.mq.metrics.destination.topic.t1.consume.deny.user=*
topic.mq.metrics.destination.topic.t1.consume.allow.user=user3

Depending on the sensitivity of metrics data, you can also connect your metrics monitoring client to a broker using an encrypted connection. For information on using encrypted connections, see Message Encryption.

Metrics Outputs: Metrics Messages

The metrics data outputs you get using the message-based monitoring API is a function of the metrics monitoring client you write. You are limited only by the data provided by the metrics generator in the broker. For a complete list of this data, see Chapter 18, Metrics Reference.