Useful commands to monitor and troubleshoot HornetQ in JBoss EAP 6

The JBoss Enterprise Application Platform (JBoss EAP) is a Java EE application server runtime platform used for building, deploying, and hosting Java applications and services. JBoss EAP 6 is Java EE 6 certified with Red Hat support.

HornetQ is an open source project to build a multi-protocol, embeddable, very high performance, clustered, asynchronous messaging system and is also developed by Red Hat. HornetQ is the Java Message Service (JMS) provider for JBoss EAP 6 and is configured as the Messaging Subsystem.

The following contains a collection of useful commands and steps in monitoring and troubleshooting HornetQ. Note that the commands below were run on a Windows machine with a default standalone setup of JBoss EAP with the messaging subsytem configured and a test queue created.

Before you continue if you are attempting to do this in a production environment then it is very important to backup your messaging data folders or anything else you may need. 

Finding the message count of a queue

• Open a command prompt and run the jboss-cli script from within the JBOSS_HOME bin directory:
• %JBOSS_HOME%/bin/jboss-cli.bat -c 

/subsystem=messaging/hornetq-server=default/jms-queue=testQueue/:count-messages

• If the outcome was a success the result should contain how many messages are in the queue. 

Listing the messages in a queue

• Still connected to the JBoss command line interface run the following command:

/subsystem=messaging/hornetq-server=default/jms-queue=testQueue/:list-messages

Moving messages

• You can move all messages from a one queue to another:

/subsystem=messaging/hornetq-server=default/jms-queue=testQueue/:move-messages(other-queue-name=destinationQueue)

• You can move a message from one queue to another if you know the message id of the message you want to move. You should be able to get this from listing the message as described earlier:

/subsystem=messaging/hornetq-server=default/jms-queue=testQueue/:move-message(other-queue-name=destinationQueue,message-id=ID5e1b49b7-15a2-11e5-a905-89636a1272dc)

List prepared transactions

• You can list prepared transaction on the HornetQ server by running the following command:

/subsystem=messaging/hornetq-server=default/:list-prepared-transactions

Commit prepared transactions

• If you need to force commit a prepared transaction you can do so by providing the transaction-as-base-64 value found in the list-prepared-transaction command for the following command:

/subsystem=messaging/hornetq-server=default/:commit-prepared-transaction(transaction-as-base-64=AAAAAAAAAAAAAP__wADIWogIO3NWnRrMAADsLwAAAAIAAAAAAAAAAAAAAAAAAP__wADIWogIO3NWnRrMAADsFzEHAgIA)

Java utility applications

HornetQ has a number of Java utility applications that can be run in order to perform certain tasks, these classes can be found in the %JBOSS_HOME%\modules\system\layers\base\org\hornetq directory. 

ExportJournal

• Use this class to export the journal data. You can use it as a main class or through its native method exportJournal(String, String, String, int, int, String), example as main method:

java -cp %JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-commons-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-core-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-journal-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\jboss\logging\main\jboss-logging-3.1.2.GA-redhat-1.jar \
org.hornetq.core.journal.impl.ExportJournal %JBOSS_HOME%\standalone\data\messagingjournal hornetq-data hq 10485760 %JBOSS_HOME%\tmp\journalExport.dmp

XmlDataExporter

• Read the journal, page, and large-message data from a stopped instance of HornetQ and save it in an XML format to a file, example:

java -cp %JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-commons-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-core-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-journal-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\jboss\logging\main\jboss-logging-3.1.2.GA-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\jboss\netty\main\netty-3.2.6.Final.jar \
org.hornetq.core.persistence.impl.journal.XmlDataExporter %JBOSS_HOME%/standalone/data/messagingbindings %JBOSS_HOME%/standalone/data/messagingjournal %JBOSS_HOME%/standalone/data/messagingpaging $JBOSS_HOME/standalone/data/messaginglargemessages > journal-export.xml

XmlDataImporter

• Read XML output generate by the org.hornetq.core.persistence.impl.journal.XmlDataExporter class, create a core session, and send the messages to a running instance of HornetQ, example:

java -cp %JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-commons-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-core-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-journal-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\jboss\logging\main\jboss-logging-3.1.2.GA-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\jboss\netty\main\netty-3.2.6.Final.jar \
org.hornetq.core.persistence.impl.journal.XmlDataImporter journal-export.xml localhost 5445

PrintData

• PrintData writes a human-readable interpretation of the contents of a HornetQ Journal, example:

java -cp %JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-commons-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-core-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-journal-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\jboss\logging\main\jboss-logging-3.1.2.GA-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\jboss\netty\main\netty-3.2.6.Final.jar \
org.hornetq.core.persistence.impl.journal.PrintData standalone/data/messagingbindings/ standalone/data/messagingjournal/ > printData.log

PrintPages

• PrintPages writes a human-readable interpretation of the contents of a HornetQ Journal and its pages, example:

java -cp %JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-commons-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-core-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-client-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-jms-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-journal-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\hornetq\main\hornetq-server-2.3.12.Final-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\jboss\logging\main\jboss-logging-3.1.2.GA-redhat-1.jar;%JBOSS_HOME%\modules\system\layers\base\org\jboss\netty\main\netty-3.2.6.Final.jar \
org.hornetq.core.paging.PrintPages standalone/data/messagingpaging/ standalone/data/messagingjournal/ > printPages.log

Apache ActiveMQ - integrated lightweight JNDI provider

I am testing an existing application that relies heavily on JMS message processing. For development I wanted to test outside of the container instead of running a server and deploying to it every time I made a change . After a quick search in Google I stumbled upon the JNDI Support reference page for Apache ActiveMQ. I have heard of it before but I have never used it.  

"ActiveMQ will work with any JNDI provider capable of storing Java objects. However it is common to require a JNDI initial context to be able to run many JMS example programs. So we provide a simple JNDI InitialContextFactory which can be used to lookup JMS connection factory objects as well as Destination objects."

I just tried it out now and it works like a charm. My day just got a whole lot better  :-) 

WebSphere JMS Sample Application

My previous blog I outlined the steps required to configure JMS resources for WebSphere Application Server 7.0. In that blog I promised to put together a sample application that can be installed to WebSphere Application Server and demonstrates three different implementations of sending JMS messages to a queue and retrieving the messages from a queue. The sample application is an Eclipse project interchange file. If you have Rational Application Developer installed on your computer you should be able to import this project into your workspace without too much hassle. Alternatively you can always use your favourite decompression tool to extract the contents to your local drive and then view the source from there.

Below are two diagrams describing the JMS runtime resources configured for the sample application:

Programmatic / Spring implementation

EJB3 implementation

Web client
To test the application I created a very simple web application that is used to trigger the sending of a JMS text message to a queue as well as to retrieve the message from the queue. I decided to use the Spring MVC  web framework to keep things simple. Below is a screen shot of the jms-tester web page:

WebSphere SIB, JMS queues and connection factory configuration

I was recently given a task to migrate an enterprise application that was running on SAP NetWeaver across to WebSphere application server. The application had a few session beans as well as a few message-driven beans. It used JMS to publish messages to a number of queues. This blog entry outlines the steps I took to configure the JMS queues and connection factories on WebSphere. It is pretty plain and boring but is really for my own benefit to be used as a reference and who knows maybe if you are reading this it may come in handy as well.

The following configurations were done on a single server of WebSphere application server 7.0. It assumes that the user is logged into the administration console and where global security has been enabled:

Create J2C authentication user

• Security -> Global security -> Expand Java Authentication and Authorization Service -> J2C authentication data -> New
  
• Enter in the following values:
  
• Alias: myusr
  
• User ID: myusr
  
• Password: myusr
  
• Click the OK button
  
• Save to the master file configuration
  

Create group

• Users and Groups -> Manage Groups -> Create
  
• Enter in the following values:
  
• Group name: mygrp
  
• Click on the Group Membership button
  
• Add the mygrp
  
• Click the close button
  

Create user

• Users and Groups -> Manage Users -> Create
  
• Enter in the following values:
  
• User ID: myusr
  
• First name: Myusr
  
• Last name: Mysurname
  
• Password: mypassword
  
• Confirm password: mypassword
  
• Click on the Group Membership button
  
• Click the Search button
  
• Add the mygrp
  
• Click the Close button
  
• Click the Create button
  

Create SIB

• Service integration -> Buses -> New
  
• Bus Name: my_bus
  
• Bus Security: enabled
  
• Press next to enter the security wizard
  
• Complete the wizard by accepting all the defaults
  
• Save your changes by clicking the save link
  

Configure Authorization for the SIB

• Service integration -> Buses
  
• Select the Enabled link for the my_bus
  
• [Authorization Policy] -> Users and groups in the bus connector role -> New
  
• Enable Groups radio button and click the Next button
  
• Select the mygrp checkbox and then the Next button
  
• Click the OK button
  
• Save to the master file configuration
  

Create Bus member for SIB

• Service integration -> Buses -> my_bus -> [Topology] Destinations -> Bus members -> Add button
  
• Enable the server radio button
  
• Click the Next button
  
• Enable the File store radio button
  
• Finish the wizard by accepting all defaults
  
• Save to the master file configuration
  

Create destinations for SIB

• Service integration -> Buses -> my_bus -> [Destinations resources] Destinations -> New
  
• Type: Queue
  
• Next
  
• Identifier: myFirstD
  
• Select the bus member you created in the previous step
  
• Finish the wizard by accepting all defaults
  
• Save to the master file configuration
  

Configuring authorization on queue destinations
Optional because already has AllAuthenticated by default however it is recommended to remove this and add your own

• Service integration -> Buses
  
• Select the Enabled link for the my_bus
  
• [Authorization Policy] -> Manage destination access roles
  
• Select the myFirstD destination
  
• Select the Add button
  
• Enable Groups radio button and click the Next button
  
• Select the mygrp checkbox and then the Next button
  
• Check the Sender, Receiver and Browser checkboxes
  
• Click the Finish button
  
• Click the OK button
  
• Save to the master file configuration
  

Create Connection Factory (Can also create Queue / Topic Connection Factory in a similar way)

• Resources -> JMS -> Connection factories -> select server scope from the drop down list -> New
  
• Default messaging provider -> Next
  
• Enter in the following values:
  
• Name: MyConnectionFactory
  
• JNDI name: jms/MyConnectionFactory
  
• Bus name: my_bus
  
• Container-managed authentication alias: myusr
  
• Click the OK button
  
• Save to the master file configuration
  

Create JMS Queues (Can also create Topics in a similar way)

• Resources -> JMS -> Queues -> select server scope from the drop down list -> New
  
• Select the Default messaging provider radio button
  
• Click the OK button
  
• Enter in the following values:
  
• Name: myFirstQ
  
• JNDI name: jms/myFirstQ
  
• Bus name: my_bus
  
• Queue name: myFirstD
  
• Select the OK button
  
• Save to the master file configuration
  

Create Activation specifications

• Resources -> JMS -> Activation specifications -> select server scope from the drop down list -> New
  
• Select the Default messaging provider radio button
  
• Click the OK button
  
• Enter in the following values:
  
• Name: myFirstSpec
  
• JNDI name: eis/myFirstSpec
  
• Destination type: Queue
  
• Destination JNDI name: jms/myFirstQ
  
• Bus name: my_bus
  
• Authentication alias: myusr
  
• Select the OK button
  
• Save to the master file configuration
  

That's all there is to it. The next step will be configuring you application's resources and assigning them the correct authentication methods. I will describe those steps in my next blog along with a sample application.