8 Monitoring JMS Statistics and Managing Messages

You can monitor and manage JMS statistics in Oracle WebLogic Server. You can 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 WebLogic Remote 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.

For more information about the WebLogic Diagnostic Service, see Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

This chapter includes the following sections:

• Monitoring JMS Statistics
  Once WebLogic JMS has been configured, applications can begin sending and receiving messages through the JMS API.
• Managing JMS Messages
  WebLogic JMS message monitoring and management features let you create new messages, delete selected messages, move messages to another queue, export message contents to another file, import message contents from another file, or delete all the messages from a queue.

Monitoring JMS Statistics

Once WebLogic JMS has been configured, applications can begin sending and receiving messages through the JMS API.

See Developing a Basic JMS Application in Developing JMS Applications for Oracle WebLogic Server.

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

• Monitoring JMS Servers
  
• Monitoring Queues
  
• Monitoring Topics
  
• Monitoring Durable Subscribers for Topics
  
• Monitoring Uniform Distributed Queues
  
• Monitoring Uniform Distributed Topics
  
• Monitoring Pooled JMS Connections
  

Monitoring JMS Servers

You can monitor statistics on active JMS servers defined in your domain using the WebLogic Remote 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.

To monitor JMS servers using the Remote Console, in the Monitoring Tree, go to Services, then Messaging, then JMS Servers. Select the JMS Server for which you want to see statistics.

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

• Monitor Cluster Targeted JMS Servers
  
• Monitoring Active JMS Destinations
  
• Monitoring Active JMS Transactions
  
• Monitoring Active JMS Connections, Sessions, Consumers, and Producers
  
• Monitoring Active JMS Session Pools
  

Monitor Cluster Targeted JMS Servers

Cluster targeted JMS services such as JMS Servers, SAF agents, path service, and persistent stores have multiple instances of the associated RuntimeMbeans to monitor the statistics for each respective instance in a dynamic cluster. The runtime MBeans for a JMS server and persistent store are automatically named according to the corresponding server instance name using the following pattern:

configured_JMS_service_Artifact_name@server-name

server-name is the configured server name concatenated with dynamic server instance number.

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.

In the Remote Console, go to the Monitoring Tree: Services: Messaging: JMS Servers. Select the JMS Server for which you want to see the active destinations.

Monitoring Active JMS Transactions

You can monitor active transactions running on a JMS server.

In the Remote Console, go to the Monitoring Tree: Services: Messaging: JMS Servers. Select the JMS Server for which you want to see the active transactions.

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.

In the Remote Console, go to the Monitoring Tree: Services: Messaging: JMS Servers. Select the JMS Server for which you want to see the active JMS server connections.

Using the JMS server's 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.

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.

In the Remote Console, in the Monitoring Tree, go to Services: Messaging: JMS Servers: myJMSServer. Select Session Pool Runtimes to monitor the runtime statistics provided for active JMS session pools.

Monitoring Queues

You can monitor statistics on queue resources in JMS modules using the WebLogic Remote 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.

In the Remote Console, in the Monitoring Tree, go to Services: Messaging: JMS Servers: myJMSServer. Select Destinations: myDestinationResource to monitor queue resources.

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

Monitoring Topics

You can monitor statistics on topic resources in JMS modules using the WebLogic Remote 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.

In the Remote Console, in the Monitoring Tree, go to Services: Messaging: JMS Servers: myJMSServer. Select Destinations: myDestinationResource to monitor topic resources.

Monitoring Durable Subscribers for Topics

You can monitor statistics on all the durable subscribers that are running on your JMS topics using the WebLogic Remote 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 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 using the WebLogic Remote 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.

In the Remote Console, in the Monitoring Tree, go to Services: Messaging: JMS Servers: myJMSServer. Select Destinations: myDestinationResource to monitor uniform distributed queue resources.

You can also use the WebLogic Remote 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 using the WebLogic Remote Console or through the JMSDestinationRuntimeMBean. A distributed topic resource is a single set of topics that is 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.

In the Remote Console, in the Monitoring Tree, go to Services: Messaging: JMS Servers: myJMSServer. Select Destinations: myDestinationResource to monitor uniform distributed topic resources.

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

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

• JMS Message Management Using Jakarta APIs
  
• JMS Message Management Using WebLogic Remote Console
  
• Managing Transactions
  
• Managing Durable Topic Subscribers
  

JMS Message Management Using Jakarta APIs

WebLogic Java Management Extensions (JMX) enables you to access the JMSDestinationRuntimeMBean and JMSDurableSubscriberRuntimeMBean to manage messages on JMS queues and topic durable subscribers. See Accessing WebLogic Server MBeans with JMX in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.

In WebLogic JMS, there are various states for messages. You can use these states to help manage your messages as described in the following sections. For information on valid message states, see weblogic.jms.extensions.JMSMessageInfo in Java API Reference for Oracle WebLogic Server.

JMS Message Management Using WebLogic Remote Console

You can use WebLogic Remote Console to manage JMS messages that are available on the standalone queue, distributed queue, or durable topic subscriber that you are monitoring. You can review all messages or specify filtering criteria to retrieve a specific set of messages. You can also customize the message tables to show only the information you need.

You can select a message to view its contents, move messages, import and export messages, and delete one or more messages.

For more information about using WebLogic Remote Console to manage messages on standalone queues, distributed queues, and durable subscribers, see Manage JMS Messages in Oracle WebLogic Remote Console Online Help.

• Monitoring Message Runtime Information
  
• Querying Messages
  
• Moving Messages
  
• Deleting Messages
  
• Creating New Messages
  
• Importing Messages
  
• Exporting Messages
  

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.

• JMSMessageID: A unique identifier for the message.

• JMSCorrelationID: A correlation ID is a user-defined identifier for the message, often used to correlate messages about the same subject

• JMSTimestamp: The time the message arrived on the queue. WebLogic JMS writes the time stamp in the message when it accepts the message for delivery, not when the application sends the message.

• State: The current state of a message, which could be one of DELAYED, EXPIRED, ORDERED, PAUSED, RECEIVE, REDELIVERY_COUNT_EXCEEDED, SEND, TRANSACTION, or VISIBLE.

• JMSDeliveryMode: The delivery mode is either Persistent or Non-Persistent.

• MessageSize: The size of a message in bytes.

You can choose which of the columns are visible.

By default, messages are displayed in the order in which they arrived at the destination. You can sort messages by JMSMessageID, in either ascending or descending order. To reload the default sort order (by message arrival), click View tab and return to Messages again.

Querying Messages

The Message Selector field at the top of the JMS Message Management page lets 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.

The following are examples of selector expressions.

salary > 64000 and dept in ('eng','qa')
(product like 'WebLogic%' or product like '%T3') 
       and version > 3.0
hireyear between 1990 and 1992 
       or fireyear is not null
fireyear - hireyear > 4

For more information about the message selector syntax, see the javax.jms.Message Javadoc, available at https://javaee.github.io/javaee-spec/javadocs/javax/jms/Message.html.

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, then a duplicate message with the same identifier is added to the destination.

Deleting Messages

You can delete a specific message or delete 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 about JMS message properties, see Understanding WebLogic JMS in Developing JMS Applications for Oracle WebLogic Server.

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.

Note:

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

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.

  Note:

  While importing a JMS message is similar in result to creating or publishing a new JMS message, messages with a defined (non-zero) ExpirationTime behave differently when imported, but since the message management API's ExpirationTime is absolute for imported messages. Whereas, the message send API's ExpirationTime is relative to the time the message is sent.

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.

Note:

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

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.

Note:

Generally, JMS applications can use the JMSReplyTo header field to return a response to a request. However, the information in the JMSReplyTo field is not a usable destination object and will not be valid following export or import.

Managing Transactions

When a message is produced or consumed as part of a global transaction, the message is essentially locked by the transaction and remains 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 WebLogic Remote 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. In the Remote Console, go to the Monitoring Tree: Services: Messaging: JMS Servers. Select the JMS Server for which you want to manage transactions.

For more information about JMS transactions, see Using Transactions with WebLogic JMS in Developing JMS Applications for Oracle WebLogic Server.

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 delete all messages for a subscription.