Monitoring JMS Statistics and Managing Messages

This release of WebLogic Server includes the WebLogic Diagnostic Service, which is a monitoring and diagnostic service that runs within the WebLogic Server process and participates in the standard server life cycle. This service enables you to create, collect, analyze, archive, and access diagnostic data generated by a running server and the applications deployed within its containers.

For WebLogic JMS, you can use the enhanced runtime statistics to monitor the JMS servers and destination resources in your WebLogic domain to see if there is a problem. If there is a problem, you can use profiling to determine which application is the source of the problem. Once you’ve narrowed it down to the application, you can then use JMS debugging features to find the problem within the application.

For more information on configuring JMS diagnostic notifications, debugging options, message life cycle logging, and controlling message operations on JMS destinations, see Troubleshooting WebLogic JMS.

Message administration tools in this release enhance your ability to view and browse all messages, and to manipulate most messages in a running JMS Server, using either the Administration Console or through new public runtime APIs. These message management enhancements include message browsing (for sorting), message manipulation (such as create, move, and delete), message import and export, as well as transaction management, durable subscriber management, and JMS client connection management.

The following sections explain how to monitor JMS resource statistics and how to manage your JMS messages from the Administration Console:

Monitoring JMS Statistics

Once WebLogic JMS has been configured, applications can begin sending and receiving messages through the JMS API, as described in Developing a Basic JMS Application in Programming WebLogic JMS.

You can monitor statistics for the following JMS resources: JMS servers, connections, queue and topic destinations, JMS server session pools, pooled connections, active sessions, message producers, message consumers, and durable subscriptions on JMS topics.

JMS statistics continue to increment as long as the server is running. Statistics are reset only when the server is rebooted.

Monitoring JMS Servers

You can monitor statistics on active JMS servers defined in your domain via the Administration Console or through the JMSServerRuntimeMBean. JMS servers act as management containers for JMS queue and topic resources within JMS modules that are specifically targeted to JMS servers.

For more information on using the Administration Console to monitor JMS servers, see Monitor JMS servers in the Administration Console Online Help.

When monitoring JMS servers with the Administration Console, you can also monitor statistics for active destinations, transactions, connections, and session pools.

Monitoring Active JMS Destinations

You can monitor statistics on all the active destinations currently targeted to a JMS server. JMS destinations identify queue or topic destination types within JMS modules that are specifically targeted to JMS servers.

Monitoring Active JMS Transactions

For more information on the runtime statistics provided for active JMS transactions, see JMS Server: Monitoring: Active Transactions in the Administration Console Online Help.

Monitoring Active JMS Connections, Sessions, Consumers, and Producers

You can monitor statistics on all the active JMS connections to a JMS server. A JMS connection is an open communication channel to the messaging system.

For more information on the runtime statistics provided for active JMS server connections, see JMS Server: Monitoring: Active Connections in the Administration Console Online Help.

Using the JMS server’s Active Connections monitoring page, you can also monitor statistics on all the active JMS sessions, consumers, and producers on your server. A session defines a serial order for both the messages produced and the messages consumed, and can create multiple message producers and message consumers. The same thread can be used for producing and consuming messages.

For more information on using the Administration Console to monitor session, consumers, and producers, see the following topics in the Administration Console Online Help:

Monitoring Active JMS Session Pools

You can monitor statistics on all the active JMS session pools defined for a JMS server. Session pools enable an application to process messages concurrently.

For more information on the runtime statistics provided for active JMS session pools, see JMS Server: Monitoring: Active Session Pools in the Administration Console Online Help.

Monitoring Queues

You can monitor statistics on queue resources in JMS modules via the Administration Console or through the JMSDestinationRuntimeMBean. A JMS queue defines a point-to-point destination type for a JMS server. Queues are used for synchronous peer communications. A message delivered to a queue will be distributed to one consumer.

For more information on using the Administration Console to monitor queue resources, see Monitor queues in JMS system modules in the Administration Console Online Help.

You can also use the Administration Console to manage messages on queues, as described in Managing JMS Messages.

Monitoring Topics

You can monitor statistics on topic resources in JMS modules via the Administration Console or through the JMSDestinationRuntimeMBean. A JMS topic identifies a publish/subscribe destination type for a JMS server. Topics are used for asynchronous peer communications. A message delivered to a topic will be distributed to all topic consumers.

For more information on using the Administration Console to monitor topic resources, see Monitor topics in JMS system modules in the Administration Console Online Help.

Monitoring Durable Subscribers for Topics

You can monitor statistics on all the durable subscribers that are running on your JMS topics via the Administration Console or through the JMSDurableSubscriberRuntimeMBean. Durable subscribers allow you to assign a name to a topic subscriber and associate it with a user or application. WebLogic stores durable subscribers in a persistent file-base store or JDBC-accessible database until the message has been delivered to the subscribers or has expired, even if those subscribers are not active at the time that the message is delivered.

You can use the Administration Console to manage durable subscribers running on topics, as described in Managing JMS Messages.

Monitoring Uniform Distributed Queues

You can monitor statistics on uniform distributed queue resources in JMS modules via the Administration Console or through the JMSDestinationRuntimeMBean. A distributed queue resource is a single set of queues that are accessible as a single, logical destination to a client (for example, a distributed topic has its own JNDI name). The members of the unit are usually distributed across multiple servers within a cluster, with each member belonging to a separate JMS server.

For more information on using the Administration Console to monitor uniform distributed queue resources, see Uniform distributed queues - monitor statistics in the Administration Console Online Help.

You can also use the Administration Console to manage messages on distributed queues, as described in Managing JMS Messages.

Monitoring Uniform Distributed Topics

You can monitor statistics on uniform distributed topic resources in JMS modules via the Administration Console or through the JMSDestinationRuntimeMBean. A distributed topic resource is a single set of topics that are accessible as a single, logical destination to a client (for example, a distributed topic has its own JNDI name). The members of the unit are usually distributed across multiple servers within a cluster, with each member belonging to a separate JMS server.

For more information on using the Administration Console to monitor uniform distributed topic resources, see Uniform distributed queues - monitor statistics in the Administration Console Online Help.

Monitoring Pooled JMS Connections

You can monitor statistics on all the active pooled JMS connections on your server. A pooled JMS connection is a session pool used by EJBs and servlets that use a resource-reference element in their EJB or servlet deployment descriptor to define their JMS connection factories.

Managing JMS Messages

The WebLogic JMS message monitoring and management features allow you to create new messages, delete selected messages, move messages to another queue, export message contents to another file, import message contents from another file, or drain all the messages from the queue.

JMS Message Management Using Java APIs

JMS Message Management Using the Administration Console

The JMS Message Management page of the Administration Console summarizes the messages that are available on the standalone queue, distributed queue, or durable topic subscriber you that you are monitoring. You can page through messages and/or retrieve a set of messages that meet filtering criteria you specify. You can also customize the message display to show only the information you need. From this page, you can select a message to display its contents, create new messages, delete one or more messages, move messages, import and export messages, and drain (delete) all of the messages from the queue or durable subscription.

For more information on using the Administration Console to manage messages on standalone queues, distributed queues, and durable subscribers, see the following instructions in the Administration Console Online Help:

Each message management function is described in detail in the following sections.

Monitoring Message Runtime Information

By default, the JMS Message Management page displays the information about each message on a queue or durable subscriber in a table with the following columns.

ID - A unique identifier for the message.
Type - The JMS message type, such as BytesMessage, TextMessage, StreamMessage, ObjectMessage, MapMessage, or XMLMessage.
CorrId - A correlation ID is a user-defined identifier for the message, often used to correlate messages about the same subject
Priority - An indicator of the level of importance or urgency of the message, with 0 as the lowest priority and 9 as the highest. Usually, 0-4 are gradients of normal priority and 5-9 are gradients of expedited priority. Priority is set to 4 by default.
Timestamp - The time the message arrived on the queue.

You can change the order in which the columns are listed and choose which of the columns will be included in and which excluded from the display. You can also increase the number of messages displayed on the page from 10 (default) to 20 or 30.

By default, messages are displayed in the order in which they arrived at the destination. You can choose to display the messages in either ascending or descending order by message ID instead by clicking on the ID column header. However, you cannot restore the initial sort order once you have altered it; you must return to the JMS System Module Resources page and reselect the queue to see the messages in order of arrival again.

Querying Messages

The Message Selector field at the top of the JMS Message Management page enables you to filter the messages on the queue based on any valid JMS message header or property with the exception of JMSXDeliveryCount. A message selector is a boolean expression. It consists of a String with a syntax similar to the where clause of an SQL select statement.

For more information about the message selector syntax, see the javax.jms.Message Javadoc.

Moving Messages

You can forward a message from a source destination to a target destination under the following conditions:

The source destination is either a queue or a topic durable subscriber in the consumption-paused state.

Note:

For more information about consumption-paused states, see Consumption Pause and Consumption Resume.

The message state is either visible, delayed, or ordered.
The target destination is:

in the same cluster as the source destination
either a queue, a topic, or a topic durable subscriber
not in the production-paused state

Note:

For more information about production-paused states, see Production Pause and Production Resume.

The message identifier does not change when you move a message. If the message being moved already exists on the target destination, a duplicate message with the same identifier is added to the destination.

Deleting Messages

You can delete a specific message or drain all messages from a queue or topic durable subscriber under the following conditions:

The destination is in the consumption-paused state.

Note:

For more information about consumption-paused states, see Consumption Pause and Consumption Resume.

The message state is either visible, delayed, or ordered.

The destination is locked while the delete operation occurs. If there is a failure during the delete operation, it is possible that only a portion of the messages selected will be deleted.

Creating New Messages

You can create new messages to be sent to a destination. To produce a new message, provide the following information:

Message type – such as BytesMessage, TextMessage, StreamMessage, ObjectMessage, MapMessage, or XMLMessage.
Correlation ID – a user-defined identifier for the message, often used to correlate messages about the same subject.
Expiration – specifies the expiration, or time-to-live value, for a message.
Priority – an indicator of the level of importance or urgency of the message, with 0 as the lowest priority and 9 as the highest. Usually, 0-4 are gradients of normal priority and 5-9 are gradients of expedited priority. Priority is set to 4 by default.
Delivery Mode – specifies PERSISTENT or NON_PERSISTENT messaging.
Delivery Time – defines the earliest absolute time at which a message can be delivered to a consumer.
Redelivery Limit – the number of redelivery tries a message can have before it is moved to an error destination.
Header – every JMS message contains a standard set of header fields that is included by default and available to message consumers. Some fields can be set by the message producers.
Body – the message content.

For more information on JMS message properties, see Understanding WebLogic JMS in Programming WebLogic JMS.

Importing Messages

Importing a message in XML format results in the creation or replacement of a message on the specified destination. The target destination for an imported message can be either a queue or a topic durable subscriber. The destination must be in a production-paused state.

If a message being replaced with an imported file is associated with a JMS transaction, the imported replacement will still be associated with the transaction.

When a new message is created or an existing message is replaced with an imported file, the following rules apply:

Quota limits are enforced for both new messages and replacement messages.
The delivery count of the imported message is set to zero.
A new message ID is generated for each imported message.
If the imported message specifies a delivery mode of PERSISTENT and the target destination has no store, the delivery mode is changed to NON-PERSISTENT.

Exporting Messages

Exporting a message results in a JMS message that is converted to either XML or serialized format. The source destination must be in a production-paused state.

Temporary destinations enable an application to create a destination, as required, without the system administration overhead associated with configuring and creating a server-defined destination.

Managing Transactions

When a message is produced or consumed as part of a global transaction, the message is essentially locked by the transaction and will remain locked until the transaction coordinator either commits or aborts the JMS branch. If the coordinator is not able to communicate the outcome of the transaction to the JMS server due to a failure, the message(s) associated with the transaction may remain pending for a long time.

The JMS server transaction management features available through the Administration Console allow you to:

Identify in-progress transactions for which a JMS server is a participant.
Identify messages associated with a JMS transaction branch.
Force the outcome of pending JMS transaction branches, either by committing them or rolling them back.
Manage JMS client connections.

You can view all the JMS connections on a particular WebLogic Server instance and get address and port information for each process that is holding a connection. You can also terminate a connection. For more information on using the Administration Console to manage transactions for a JMS server, see JMS Server: Monitoring: Active Transactions in the Administration Console Online Help.

Managing Durable Topic Subscribers

You can view a list of durable subscribers for a given topic, browse messages associated with a subscriber, create and delete subscribers, and delete selected messages or purge all messages for a subscription.

Configuring and Managing WebLogic JMS

Monitoring JMS Statistics and Managing Messages