Using the Message-Based Monitoring API

Message Queue provides a Metrics Message Producer, which receives information
from the Metrics Generator at regular intervals and writes the information
into metrics messages,. The Metrics Message Producer
then sends these messages to one of a number of metric topic destinations,
depending on the type of metric information contained in the messages.

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

Table 13–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

The broker properties imq.metrics.topic.enabled and imq.metrics.topic.interval control, respectively, whether messages are sent to metric topic
destinations and how often. The imq.metrics.topic.timetolive and imq.metrics.topic.persist properties specify the lifetime of such messages and whether they
are persistent.

Besides the information contained in the body of a metrics message,
the header of each message includes properties that provide the following
additional information:

The message type

The address (host name and port number) of the broker that
sent the message

The time the metric sample was taken

These properties are useful to client applications that process metrics
messages of different types or from different brokers.

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.

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.

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.

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 21, Metrics Information Reference.