4 Using the Metrics Monitoring API

To Implement Message-Based Monitoring

1. The developer designs and writes a client that subscribes to one or more metrics destinations.

2. The administrator sets those metrics-related broker properties whose default values are not satisfactory.

3. (Optional) The administrator sets entries in the access.control.properties file to restrict access to metrics information.

4. The developer or the administrator starts the metrics monitoring client.

   When consumers subscribe to a metrics topic, the topic's physical destination is automatically created. After the metrics topic has been created, the broker's metrics message producer begins to send metrics messages to the appropriate destination.

JVM Metrics

The messages you receive when you subscribe to the topic mq.metrics.jvm have the type property set to mq.metrics.jvm in the message header and have the data listed in Table 4-3 in the message body.

freeMemory

maxMemory

totalMemory

Destination-List Metrics

The messages you receive when you subscribe to a topic named mq.metrics.destination_list have the type property set to mq.metrics.destination_list in the message header.

The message body contains a list of map names. Each destination on the broker is specified by a unique map name (a name-value pair) in the message body. The type of the name-value pair is hashtable.

The name (in the name-value pair) depends on whether the destination is a queue or a topic, and is constructed as follows:

• mq.metrics.destination.queue.monitored_destination_name

• mq.metrics.destination.topic.monitored_destination_name

The value (in the name-value pair) is an object of type java.util.Hashtable . This hashtable contains the key-value pairs described in Table 4-4.

Notice that the destination name and type could be extracted directly from the metrics topic destination name, but the hashtable includes it for your convenience.

By enumerating through the map names and extracting the hashtable described in Table 4-4, you can form a complete list of destination names and some of their characteristics.

The destination list does not include the following kinds of destinations:

• Destinations that are used by Message Queue administration tools

• Destinations that the Message Queue broker creates for internal use

Destination Metrics

The messages you receive when you subscribe to the topic mq.metrics.destination.queue.monitored_destination_name have the type property mq.metrics.destination.queue.monitored_destination_name set in the message header. The messages you receive when you subscribe to the topic mq.metrics.destination.topic.monitored_destination_name have the type property mq.metrics.destination.topic. monitored_destination_name set in the message header. Either of these messages has the data listed in Table 4-5 in the message body.

numActiveConsumers

avgNumActiveConsumers 

peakNumActiveConsumers 

numBackupConsumers 

avgNumBackupConsumers

peakNumBackupConsumers

numMsgsIn

numMsgsOut 

numMsgs

avgNumMsgs

peakNumMsgs 

msgBytesIn

msgBytesOut

totalMsgBytes

avgTotalMsgBytes

peakTotalMsgBytes

peakMsgBytes

diskReserved

diskUsed

diskUtilizationRatio

A Destination List Metrics Example

The source file for this code example is DestListMetrics.java. This client application monitors the list of destinations on a broker by subscribing to the topic mq.metrics.destination_list. The messages that arrive contain information describing the destinations that currently exist on the broker, such as destination name, destination type, and whether the destination is temporary.

Example 4-3 shows how to subscribe to mq.metrics.destination_list.

com.sun.messaging.TopicConnectionFactory metricConnectionFactory;
TopicConnection              metricConnection;
TopicSession                 metricSession;
TopicSubscriber              metricSubscriber;
Topic                        metricTopic;
String                       metricTopicName = null;

metricConnectionFactory = new com.sun.messaging.TopicConnectionFactory();
metricConnection = metricConnectionFactory.createTopicConnection();
metricConnection.start();

metricSession = metricConnection.createTopicSession(false,
                    Session.AUTO_ACKNOWLEDGE);

metricTopicName = "mq.metrics.destination_list";
metricTopic = metricSession.createTopic(metricTopicName);

metricSubscriber = metricSession.createSubscriber(metricTopic);
metricSubscriber.setMessageListener(this);
               

The incoming message is processed in the onMessage() method, as shown in Example 4-4:

public void onMessage(Message m)  {
    try{
         MapMessage mapMsg = (MapMessage)m;
         String type = mapMsg.getStringProperty("type");

         if (type.equals(metricTopicName))  {
             String oneRow[] = new String[ 3 ];

             /*
             * Extract metrics
             */
             for (Enumeration e = mapMsg.getMapNames();
                  e.hasMoreElements();) {

                  String metricDestName = (String)e.nextElement();
                  Hashtable destValues =
                                (Hashtable)mapMsg.getObject(metricDestName);
                  int i = 0;

                  oneRow[i++] = (destValues.get("name")).toString();
                  oneRow[i++] = (destValues.get("type")).toString();
                  oneRow[i++] = (destValues.get("isTemporary")).toString();

                  mp.add(oneRow);
             }

             mp.print();
             System.out.println("");

             mp.clear();
         } else  {
                System.err.println("Msg received:
                        not destination list metric type");
            }
    } catch (Exception e)  {
            System.err.println("onMessage: Exception caught: " + e);
    }
}               

Notice how the metrics type is extracted and checked, and how the list of destinations is extracted. By iterating through the map names in mapMsg and extracting the corresponding value (a hashtable), you can construct a list of all the destinations and their related information.

As discussed in Format of Metrics Messages, these map names are metrics topic names having one of two forms:

mq.metrics.destination.queue.monitored_destination_name

mq.metrics.destination.topic.monitored_destination_name

(The map names can also be used to monitor a destination, but that is not done in this particular example.)

Notice that from each extracted hashtable, the information on each destination is extracted using the keys name, type, and isTemporary. The extraction code from the previous code example is reiterated here for your convenience.

String metricDestName = (String)e.nextElement();
        Hashtable destValues = (Hashtable)mapMsg.getObject(metricDestName);
        int i = 0;

        oneRow[i++] = (destValues.get("name")).toString();
        oneRow[i++] = (destValues.get("type")).toString();
        oneRow[i++] = (destValues.get("isTemporary")).toString();
               

Run this example monitoring client with the following command:

java DestListMetrics

The output looks like the following:

---------------------------------------------------
Destination Name       Type          IsTemporary
---------------------------------------------------
SimpleQueue            queue          false
fooQueue               queue          false
topic1                 topic          false
   

A Destination Metrics Example

The source file for this code example is DestMetrics.java. This client application monitors a specific destination on a broker. It accepts the destination type and name as parameters, and it constructs a metrics topic name of the form mq.metrics.destination.queue.monitored_destination_name or mq.metrics.destination.topic.monitored_destination_name .

Example 4-6 shows how to subscribe to the metrics topic for monitoring a specified destination.

com.sun.messaging.TopicConnectionFactory metricConnectionFactory;
TopicConnection             metricConnection;
TopicSession                metricSession;
TopicSubscriber             metricSubscriber;
Topic                       metricTopic;
String                      metricTopicName = null;
String                      destName = null,
                            destType = null;

for (int i = 0; i < args.length; ++i)  {
    ...
    } else if (args[i].equals("-n"))  {
            destName = args[i+1];
    } else if (args[i].equals("-t"))  {
            destType = args[i+1];
    }
}

metricConnectionFactory = new com.sun.messaging.TopicConnectionFactory();

metricConnection = metricConnectionFactory.createTopicConnection();
metricConnection.start();

metricSession = metricConnection.createTopicSession(false,
                   Session.AUTO_ACKNOWLEDGE);

if (destType.equals("q"))  {
    metricTopicName = "mq.metrics.destination.queue." + destName;
} else  {
    metricTopicName = "mq.metrics.destination.topic." + destName;
}

metricTopic = metricSession.createTopic(metricTopicName);

metricSubscriber = metricSession.createSubscriber(metricTopic);
metricSubscriber.setMessageListener(this);

The incoming message is processed in the onMessage() method, as shown in Example 4-7:

public void onMessage(Message m)  {
   try {
        MapMessage mapMsg = (MapMessage)m;
        String type = mapMsg.getStringProperty("type");

        if (type.equals(metricTopicName))  {
            String oneRow[] = new String[ 11 ];
            int i = 0;

            /*
            * Extract destination metrics
            */
            oneRow[i++] = Long.toString(mapMsg.getLong("numMsgsIn"));
            oneRow[i++] = Long.toString(mapMsg.getLong("numMsgsOut"));
            oneRow[i++] = Long.toString(mapMsg.getLong("msgBytesIn"));
            oneRow[i++] = Long.toString(mapMsg.getLong("msgBytesOut"));

            oneRow[i++] = Long.toString(mapMsg.getLong("numMsgs"));
            oneRow[i++] = Long.toString(mapMsg.getLong("peakNumMsgs"));
            oneRow[i++] = Long.toString(mapMsg.getLong("avgNumMsgs"));

            oneRow[i++] = Long.toString(mapMsg.getLong("totalMsgBytes")/1024);
            oneRow[i++] = Long.toString
                                   (mapMsg.getLong("peakTotalMsgBytes")/1024);
            oneRow[i++] = Long.toString
                                   (mapMsg.getLong("avgTotalMsgBytes")/1024);

            oneRow[i++] = Long.toString(mapMsg.getLong("peakMsgBytes")/1024);

            mp.add(oneRow);
            ...
            }
    } catch (Exception e)  {
            System.err.println("onMessage: Exception caught: " + e);
    }
}               

Notice how the metrics type is extracted, using the getStringProperty() method as in the previous examples, and is checked. Also notice how various destination data are extracted, using the getLong() method of mapMsg.

You can run this example monitoring client with one of the following commands:

java DestMetrics -t t -n topic_name
java DestMetrics -t q -n queue_name

Using a queue named SimpleQueue as an example, the command would be:

java DestMetrics -t q -n SimpleQueue

The output looks like the following:

------------------------------------------------------------------------------
Msgs       Msg   Bytes  Msg Count        Tot Msg Bytes(k)    Largest Msg
In   Out   In    Out    Curr  Peak  Avg  Curr  Peak  Avg     (k)
------------------------------------------------------------------------------
500   0   318000  0     500   500   250  310   310   155      0