JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle GlassFish Server Message Queue 4.5 Administration Guide
search filter icon
search icon

Document Information


Part I Introduction to Message Queue Administration

1.  Administrative Tasks and Tools

2.  Quick-Start Tutorial

Part II Administrative Tasks

3.  Starting Brokers and Clients

4.  Configuring a Broker

5.  Managing a Broker

6.  Configuring and Managing Connection Services

7.  Managing Message Delivery

8.  Configuring Persistence Services

9.  Configuring and Managing Security Services

10.  Configuring and Managing Broker Clusters

11.  Managing Administered Objects

12.  Configuring and Managing Bridge Services

13.  Monitoring Broker Operations

Monitoring Services

Introduction to Monitoring Tools

Configuring and Using Broker Logging

Logger Properties

Log Message Format

Default Logging Configuration

Changing the Logging Configuration

To Change the Logger Configuration for a Broker

Changing the Output Channel

Changing Log File Rollover Criteria

Sending Metrics Data to Log Files

Logging Dead Messages

Using the Command Utility to Display Metrics Interactively

imqcmd metrics

To Use the metrics Subcommand

Metrics Outputs: imqcmd metrics

Brokerwide Metrics

Connection Service Metrics

Physical Destination Metrics

imqcmd query

Using the JMX Administration API

Using the Java ES Monitoring Console

Using the Message-Based Monitoring API

Setting Up Message-Based Monitoring

To Set Up Message-based Monitoring

Security and Access Considerations

Metrics Outputs: Metrics Messages

14.  Analyzing and Tuning a Message Service

15.  Troubleshooting

Part III Reference

16.  Command Line Reference

17.  Broker Properties Reference

18.  Physical Destination Property Reference

19.  Administered Object Attribute Reference

20.  JMS Resource Adapter Property Reference

21.  Metrics Information Reference

22.  JES Monitoring Framework Reference

Part IV Appendixes

A.  Distribution-Specific Locations of Message Queue Data

B.  Stability of Message Queue Interfaces

C.  HTTP/HTTPS Support

D.  JMX Support

E.  Frequently Used Command Utility Commands


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.

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. This allows you to create custom monitoring tools to support messaging applications. For details of the metric quantities reported in each type of metrics message, see Chapter 4, Using the Metrics Monitoring API, in Oracle GlassFish Server Message Queue 4.5 Developer’s Guide for Java Clients

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
Broker metrics
Java Virtual Machine metrics
List of destinations and their types
Destination metrics for queue queueName
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:

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

  1. 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.

  2. Configure the broker’s Metrics Message Producer by setting broker property values in the 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.

  3. Set any access control you desire on metrics topic destinations.

    See the discussion in Security and Access Considerations below.

  4. 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:

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 file will deny access to the metrics topic to everyone except user1 and user 2.*,user2

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

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.