Chapter 23. Management
AMQ Broker provides both a graphical as well as a programming interface to help you manage your brokers.
23.1. Using AMQ Console
If you prefer to use a graphic interface to manage AMQ, you can use AMQ Console. AMQ Console is a web console included in the AMQ Broker installation, and it enables you to use a web browser to manage AMQ Broker and AMQ Interconnect.
For more information, see Using AMQ Console.
23.2. Using the Management API
AMQ Broker 7.0 has an extensive management API that allows a user to modify a broker’s configuration, create new resources (for example, JMS queues and topics), inspect these resources (for example, how many messages are currently held in a queue) and interact with it (for example, to remove messages from a queue). All the operations allows a client to manage the broker. They also allows clients to subscribe to management notifications.
There are three ways to manage the broker:
- Using JMX — JMX is the standard way to manage Java applications
- Using the core API — management operations are sent to the broker using Core messages
- Using the JMS API — management operations are sent to the broker using JMS messages
Although there are three different ways to manage the broker each API supports the same functionality. If it is possible to manage a resource using JMX it is also possible to achieve the same result using Core messages or JMS messages.
This choice depends on your requirements, your application settings and your environment to decide which way suits you best.
Regardless of the way you invoke management operations, the management API is the same.
For each managed resource, there exists a Java interface describing what can be invoked for this type of resource.
The broker exposes its managed resources in 2 packages:
-
Core resources are located in the
org.apache.activemq.artemis.api.core.management
package -
JMS resources are located in the
org.apache.activemq.artemis.api.jms.management
package
The way to invoke a management operations depends whether JMX, core messages, or JMS messages are used.
A few management operations require a filter
parameter to choose which messages are affected by the operation. Passing null
or an empty string means that the management operation will be performed on all messages.
23.2.1. Core Broker Management
- Listing, creating, deploying and destroying queues
A list of deployed core queues can be retrieved using the
getQueueNames()
method.Core queues can be created or destroyed using the management operations
createQueue()
ordeployQueue()
ordestroyQueue()
)on theActiveMQServerControl
(with the ObjectNameorg.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Server
or the resource namecore.server
)createQueue
will fail if the queue already exists whiledeployQueue
will do nothing.- Pausing and resuming Queues
-
The
QueueControl
can pause and resume the underlying queue. When a queue is paused, it will receive messages but will not deliver them. When it is resumed, it’ll begin delivering the queued messages, if any. - Listing and closing remote connections
-
Retrieve a client’s remote addresses by using
listRemoteAddresses()
. It is also possible to close the connections associated with a remote address using thecloseConnectionsForAddress()
method. -
Alternatively, list connection IDs using
listConnectionIDs()
and list all the sessions for a given connection ID usinglistSessions()
.
-
Retrieve a client’s remote addresses by using
- Managing Transactions
In case of a broker crash, when the broker restarts, some transactions may require manual intervention. Use the the following methods to help resolve issues you encounter.
-
List the transactions which are in the prepared states (the transactions are represented as opaque Base64 Strings) using the
listPreparedTransactions()
method lists. -
Commit or rollback a given prepared transaction using
commitPreparedTransaction()
orrollbackPreparedTransaction()
to resolve heuristic transactions. -
List heuristically completed transactions using the
listHeuristicCommittedTransactions()
andlistHeuristicRolledBackTransactions
methods.
-
List the transactions which are in the prepared states (the transactions are represented as opaque Base64 Strings) using the
- Enabling and resetting message counters
-
Enable and disable message counters using the
enableMessageCounters()
ordisableMessageCounters()
method. -
Reset message counters by using the
resetAllMessageCounters()
andresetAllMessageCounterHistories()
methods.
-
Enable and disable message counters using the
- Retrieving broker configuration and attributes
-
The
ActiveMQServerControl
exposes the broker’s configuration through all its attributes (for example,getVersion()
method to retrieve the broker’s version, and so on). - Listing, creating and destroying Core bridges and diverts
-
List deployed core bridges and diverts) using the
getBridgeNames()
andgetDivertNames()
methods respectively. -
Create or destroy using bridges and diverts using
createBridge()
anddestroyBridge()
orcreateDivert()
anddestroyDivert()
on theActiveMQServerControl
(with the ObjectNameorg.apache.activemq.artemis:module=Core,type=Server
or the resource namecore.server
).
-
List deployed core bridges and diverts) using the
- Stopping the broker and forcing failover to occur with any currently attached clients
Use the
forceFailover()
on theActiveMQServerControl
(with the ObjectNameorg.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Server
or the resource namecore.server
)NoteSince this method actually stops the broker you will probably receive some sort of error depending on which management service you use to call it.
23.2.2. Core Address Management
Manage core addresses using the AddressControl
class (with the ObjectName org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Address,name="<the address name>"
or the resource name core.address.<the address name>
).
-
Modify roles and permissions for an address using the
addRole()
orremoveRole()
methods. You can list all the roles associated to the queue with thegetRoles()
method
23.2.3. Core Queue Management
The bulk of the core management API deals with core queues. The QueueControl
class defines the Core queue management operations (with the ObjectName org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Queue,address="<the bound address>",name="<the queue name>"
or the resource name core.queue.<the queue name>
).
Most of the management operations on queues take either a single message ID (for example, to remove a single message) or a filter (for example, to expire all messages with a given property.)
- Expiring, sending to a dead letter address and moving messages
-
Expire messages from a queue using the
expireMessages()
method. If an expiry address is defined, messages will be sent to it, otherwise they are discarded. The queue’s expiry address can be set with thesetExpiryAddress()
method. -
Send Messages to a dead letter address with the
sendMessagesToDeadLetterAddress()
method. It returns the number of messages which are sent to the dead letter address. If a dead letter address is not defined, messages are removed from the queue and discarded. The queue’s dead letter address can be set with thesetDeadLetterAddress()
method. -
Move messages from one queue to another by using the
moveMessages()
method.
-
Expire messages from a queue using the
- Listing and removing messages
-
List messages from a queue using the
listMessages()
method. It will return an array ofMap
, oneMap
for each message. -
Remove messages from a queue using the
removeMessages()
method, which returns aboolean
for the single message ID variant or the number of removed messages for the filter variant. This method takes afilter
argument to remove only filtered messages. Setting the filter to an empty string will in effect remove all messages. Counting messages
The number of messages in a queue is returned by the
getMessageCount()
method. Alternatively, thecountMessages()
will return the number of messages in the queue which match a given filter.Changing message priority
The message priority can be changed by using the
changeMessagesPriority()
method which returns aboolean
for the single message ID variant or the number of updated messages for the filter variant.Message counters
Message counters can be listed for a queue with the
listMessageCounter()
andlistMessageCounterHistory()
methods (see the Message Counters section). The message counters can also be reset for a single queue using theresetMessageCounter()
method.Retrieving the queue attributes
The
QueueControl
exposes Core queue settings through its attributes (for example,getFilter()
to retrieve the queue’s filter if it was created with one,isDurable()
to know whether the queue is durable, and so on).Pausing and resuming Queues
The
QueueControl
can pause and resume the underlying queue. When a queue is paused, it will receive messages but will not deliver them. When it is resumed, it will begin delivering the queued messages, if any.
-
List messages from a queue using the
23.2.3.1. Other Core Resources Management
The broker allows to start and stop its remote resources (acceptors, diverts, bridges, and so on) so that a broker can be taken off line for a given period of time without stopping it completely (for example, if other management operations must be performed such as resolving heuristic transactions). These resources are
Acceptors
Start or stop an acceptor using the
start()
or.stop()
method on theAcceptorControl
class (with the ObjectNameorg.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Acceptor,name="<the acceptor name>"
or the resource namecore.acceptor.<the address name>
). The acceptors parameters can be retrieved using theAcceptorControl
attributes. See Network Connections:Acceptors and Connectors for more information about Acceptors.Diverts
Start or stop a divert using the
start()
orstop()
method on theDivertControl
class (with the ObjectNameorg.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Divert,name=<the divert name>
or the resource namecore.divert.<the divert name>
). Diverts parameters can be retrieved using theDivertControl
attributes.Bridges
Start or stop a bridge using the
start()
(resp.stop()
) method on theBridgeControl
class (with the ObjectNameorg.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Bridge,name="<the bridge name>"
or the resource namecore.bridge.<the bridge name>
). Bridges parameters can be retrieved using theBridgeControl
attributes. See Clustering for more information.Broadcast groups
They can be started or stopped using the
start()
orstop()
method on theBroadcastGroupControl
class (with the ObjectNameorg.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=BroadcastGroup,name="<the broadcast group name>"
or the resource namecore.broadcastgroup.<the broadcast group name>
). Broadcast groups parameters can be retrieved using theBroadcastGroupControl
attributes. See Clustering for more information.Discovery groups
Start or stop a discovery group using the
start()
orstop()
method on theDiscoveryGroupControl
class (with the ObjectNameorg.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=DiscoveryGroup,name="<the discovery group name>"
or the resource namecore.discovery.<the discovery group name>
). Discovery groups parameters can be retrieved using theDiscoveryGroupControl
attributes. See Clustering for more information.Cluster connections
Start or stop a cluster connection using the
start()
orstop()
method on theClusterConnectionControl
class (with the ObjectNameorg.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=ClusterConnection,name="<the cluster connection name>"
or the resource namecore.clusterconnection.<the cluster connection name>
). Cluster connections parameters can be retrieved using theClusterConnectionControl
attributes. See Clustering for more information.
23.2.4. JMS Broker Management
JMS Resources (connection factories and destinations) can be created using the JMSServerControl
class (with the ObjectName org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=JMS,serviceType=Server
or the resource name jms.server
).
- Listing, creating, destroying connection factories
Get a list of names of the deployed connection factories using the
getConnectionFactoryNames()
method.JMS connection factories can be created or destroyed using the
createConnectionFactory()
methods ordestroyConnectionFactory()
methods. These connection factories are bound to JNDI so that JMS clients can look them up. If a graphical console is used to create the connection factories, the transport parameters are specified in the text field input as a comma-separated list of key=value (for example,key1=10, key2="value", key3=false
).If there are multiple transports defined, you need to enclose the key/value pairs between curly braces, for example,
{key=10}, {key=20}
. In that case, the firstkey
will be associated to the first transport configuration and the secondkey
will be associated to the second transport configuration. See Network Connections: Acceptors and Connectors for more information.- Listing, creating, destroying queues
-
Get a list of names of the deployed JMS queues using the
getQueueNames()
method. -
JMS queues can be created or destroyed using the
createQueue()
methods ordestroyQueue()
methods. These queues are bound to JNDI so that JMS clients can look them up.
-
Get a list of names of the deployed JMS queues using the
- Listing, creating, and destroying topics
-
Get a list of names of the deployed topics using the
getTopicNames()
method. -
JMS topics can be created or destroyed using the
createTopic()
ordestroyTopic()
methods. These topics are bound to JNDI so that JMS clients can look them up.
-
Get a list of names of the deployed topics using the
- Listing and closing remote connections
-
Get a list of JMS Clients' remote addresses using
listRemoteAddresses()
. It is also possible to close the connections associated with a remote address using thecloseConnectionsForAddress()
method. -
Alternatively, connection IDs can be listed using
listConnectionIDs()
and all the sessions for a given connection ID can be listed usinglistSessions()
.
-
Get a list of JMS Clients' remote addresses using
23.2.4.1. JMS ConnectionFactory Management
JMS Connection Factories can be managed using the ConnectionFactoryControl
class (with the ObjectName org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=JMS,serviceType=ConnectionFactory,name="<the connection factory name>"
or the resource name jms.connectionfactory.<the connection factory name>
).
- Retrieving connection factory attributes
-
The
ConnectionFactoryControl
exposes JMS ConnectionFactory configuration through its attributes (for example,getConsumerWindowSize()
to retrieve the consumer window size for flow control,isBlockOnNonDurableSend()
to know whether the producers created from the connection factory will block when sending non-durable messages, and so on).
23.2.4.2. JMS Queue Management
JMS queues can be managed using the JMSQueueControl
class (with the ObjectName org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=JMS,serviceType=Queue,name="<the queue name>"
or the resource name jms.queue.<the queue name>
).
The management operations on a JMS queue are very similar to the operations on a core queue.
- Expiring, sending to a dead letter address, and moving messages
-
Messages can be expired from a queue by using the
expireMessages()
method. If an expiry address is defined, messages will be sent to it, otherwise they are discarded. The queue’s expiry address can be set with thesetExpiryAddress()
method. Messages can also be sent to a dead letter address with the
sendMessagesToDeadLetterAddress()
method. It returns the number of messages which are sent to the dead letter address. If a dead letter address is not defined, message are removed from the queue and discarded. The queue’s dead letter address can be set with thesetDeadLetterAddress()
method.Messages can also be moved from a queue to another queue by using the
moveMessages()
method.
-
Messages can be expired from a queue by using the
- Listing and removing messages
-
Messages can be listed from a queue by using the
listMessages()
method which returns an array ofMap
, oneMap
for each message. -
Messages can also be removed from the queue by using the
removeMessages()
method which returns aboolean
for the single message ID variant or the number of removed messages for the filter variant. TheremoveMessages()
method takes afilter
argument to remove only filtered messages. Setting the filter to an empty string will in effect remove all messages. Counting messages
The number of messages in a queue is returned by the
getMessageCount()
method. Alternatively, thecountMessages()
will return the number of messages in the queue which match a given filterChanging message priority
The message priority can be changed by using the
changeMessagesPriority()
method which returns aboolean
for the single message ID variant or the number of updated messages for the filter variant.Message counters
Message counters can be listed for a queue with the
listMessageCounter()
andlistMessageCounterHistory()
methods (see the Message Counters section).Retrieving queue attributes
The
JMSQueueControl
exposes JMS queue settings through its attributes (for example,isTemporary()
to know whether the queue is temporary,isDurable()
to know whether the queue is durable, and so on).Pausing and resuming queues
The
JMSQueueControl
can pause and resume the underlying queue. When the queue is paused it will continue to receive messages but will not deliver them. When resumed again it will deliver the enqueued messages, if any.
-
Messages can be listed from a queue by using the
23.2.4.3. JMS Topic Management
JMS Topics can be managed using the TopicControl
class (with the ObjectName org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=JMS,serviceType=Topic,name="<the topic name>"
or the resource name jms.topic.<the topic name>
).
Listing subscriptions and messages
JMS topics subscriptions can be listed using the
listAllSubscriptions()
,listDurableSubscriptions()
,listNonDurableSubscriptions()
methods. These methods return arrays ofObject
representing the subscriptions information (subscription name, client ID, durability, message count, and so on). It is also possible to list the JMS messages for a given subscription with thelistMessagesForSubscription()
method.Dropping subscriptions
Durable subscriptions can be dropped from the topic using the
dropDurableSubscription()
method.Counting subscriptions messages
The
countMessagesForSubscription()
method can be used to know the number of messages held for a given subscription (with an optional message selector to know the number of messages matching the selector)
23.2.5. Manage Via JMX
The broker can be managed using JMX. The management API is exposed by the broker using MBeans interfaces. The broker registers its resources with the domain org.apache.activemq
.
For example, the ObjectName
to manage a JMS Queue exampleQueue
is:
org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=JMS,serviceType=Queue,name="exampleQueue"
and the MBean is:
org.apache.activemq.artemis.api.jms.management.JMSQueueControl
The MBean’s ObjectName
are built using the helper class org.apache.activemq.artemis.api.core.management.ObjectNameBuilder
. You can also use jconsole
to find the ObjectName
of the MBeans you want to manage.
Managing the broker using JMX is identical to management of any Java Applications using JMX. It can be done by reflection or by creating proxies of the MBeans.
23.2.5.1. Configure JMX Management
By default, JMX is enabled to manage the broker. It can be disabled by setting jmx-management-enabled
to false
in broker.xml
:
<jmx-management-enabled>false</jmx-management-enabled>
If JMX is enabled, the broker can be managed locally using jconsole
.
Remote connections to JMX are not enabled by default for security reasons. Refer to Oracle’s Java Management Guide to configure the broker for remote management. System properties must be set in the artemis
, or artemis.cmd
for Windows installations, shell script located under INSTALL_DIR/bin
.
By default, the broker uses the JMX domain "org.apache.activemq.artemis". To manage several brokers from the same MBeanServer, the JMX domain can be configured for each individual broker by setting jmx-domain
in broker.xml
:
<jmx-domain>my.org.apache.activemq</jmx-domain>
23.2.5.2. MBeanServer Configuration
When the broker is run in standalone, it uses the Java Virtual Machine’s Platform MBeanServer
to register its MBeans. By default Jolokia is also deployed to allow access to the mbean server via rest.
23.2.5.3. Exposing JMX Using Jolokia
The default Broker configuration ships with the Jolokia http agent deployed as a Web Application. Jolokia is a remote JMX over HTTP bridge that exposed mBeans, for more information refer to the Jolokia Documentation. As a simple example, direct your web browser to the url http://localhost:8161/jolokia/read/org.apache.activemq.artemis:module=Core,type=Server/Version after starting a broker instance to query the broker’s version.
This response would give you back something like the following:
{"timestamp":1422019706,"status":200,"request":{"mbean":"org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Server","attribute":"Version","type":"read"},"value":"1.0.0.SNAPSHOT (Active Hornet, 126)"}
23.2.6. Manage Via Core API
The core management API in AMQ Broker is called by sending Core messages to a special address, the management address.
Management messages are regular Core messages with well-known properties that the broker needs to understand to interact with the management API:
- The name of the managed resource
- The name of the management operation
- The parameters of the management operation
When such a management message is sent to the management address, The broker will handle it, extract the information, invoke the operation on the managed resources and send a reply to the management message’s reply-to address (specified by ClientMessageImpl.REPLYTO_HEADER_NAME
).
A ClientConsumer
can be used to consume the management reply and retrieve the result of the operation (if any) stored in the reply’s body. For portability, results are returned as a JSON String rather than Java Serialization (the org.apache.activemq.artemis.api.core.management.ManagementHelper
can be used to convert the JSON string to Java objects).
These steps can be simplified to make it easier to invoke management operations using Core messages:
-
Create a
ClientRequestor
to send messages to the management address and receive replies. -
Create a
ClientMessage
. -
Use the helper class
org.apache.activemq.artemis.api.core.management.ManagementHelper
to fill the message with the management properties. -
Send the message using the
ClientRequestor
. -
Use the helper class
org.apache.activemq.artemis.api.core.management.ManagementHelper
to retrieve the operation result from the management reply.
For example, to find out the number of messages in the core queue exampleQueue
:
ClientSession session = ... ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management"); ClientMessage message = session.createMessage(false); ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount"); session.start(); ClientMessage reply = requestor.request(message); int count = (Integer) ManagementHelper.getResult(reply); System.out.println("There are " + count + " messages in exampleQueue");
Management operation name and parameters must conform to the Java interfaces defined in the management
packages.
Names of the resources are built using the helper class org.apache.activemq.artemis.api.core.management.ResourceNames
and are straightforward (core.queue.exampleQueue
for the Core Queue exampleQueue
, jms.topic.exampleTopic
for the JMS Topic exampleTopic
, and so on).
23.2.6.1. Configure Core Management
The management address to send management messages is configured in broker.xml
:
<management-address>jms.queue.activemq.management</management-address>
By default, the address is jms.queue.activemq.management
(it is prepended by "jms.queue" so that JMS clients can also send management messages).
The management address requires a special user permission type, manage
, to be able to receive and handle management messages. This is also configured in broker.xml:
<security-setting match="jms.queue.activemq.management"> <permission type="manage" roles="admin" /> </security-setting>
23.2.7. Manage Via JMS Messages
Using JMS messages to manage AMQ Broker is very similar to using core API.
An important difference is that JMS requires a JMS queue to send the messages to (instead of an address for the core API).
The management queue is a special queue and needs to be instantiated directly by the client:
Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
All the other steps are the same than for the Core API but they use JMS API instead:
-
Create a
QueueRequestor
to send messages to the management address and receive replies. -
Create a
Message
. -
Use the helper class
org.apache.activemq.artemis.api.jms.management.JMSManagementHelper
to fill the message with the management properties. -
Send the message using the
QueueRequestor
. -
Use the helper class
org.apache.activemq.artemis.api.jms.management.JMSManagementHelper
to retrieve the operation result from the management reply.
For example, to know the number of messages in the JMS queue exampleQueue
:
Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management"); QueueSession session = ... QueueRequestor requestor = new QueueRequestor(session, managementQueue); connection.start(); Message message = session.createMessage(); JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "messageCount"); Message reply = requestor.request(message); int count = (Integer)JMSManagementHelper.getResult(reply); System.out.println("There are " + count + " messages in exampleQueue");
23.2.7.1. Configure Management via JMS Message
Whether JMS or the core API is used for management, the configuration steps are the same. See Configure Core Management.
23.2.8. Management Notifications
The broker emits notifications to inform listeners of potentially interesting events (creation of new resources, security violation, and so on).
These notifications can be received by 3 different ways:
- JMX notifications
- Core messages
- JMS messages
23.2.8.1. JMX Notifications
If JMX is enabled (see the Configure JMX section), JMX notifications can be received by subscribing to 2 MBeans:
-
org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Server
for notifications on Core resources -
org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=JMS,serviceType=Server
for notifications on JMS resources
23.2.8.2. Core Messages Notifications
The broker defines a special management notification address. Core queues can be bound to this address so that clients will receive management notifications as Core messages.
A Core client which wants to receive management notifications must create a core queue bound to the management notification address. It can then receive the notifications from its queue.
Notifications messages are regular core messages with additional properties corresponding to the notification (its type, when it occurred, the resources which were concerned, and so on).
Since notifications are regular core messages, it is possible to use message selectors to filter out notifications and receives only a subset of all the notifications emitted by the broker.
23.2.8.2.1. Configuring The Core Management Notification Address
The management notification address to receive management notifications is configured in broker.xml
:
<management-notification-address>activemq.notifications</management-notification-address>
By default, the address is activemq.notifications
.
23.2.8.3. JMS Message Notifications
The brokers notifications can also be received using JMS messages. It is similar to receiving notifications using Core API but an important difference is that JMS requires a JMS Destination to receive the messages (preferably a Topic).
To use a JMS Destination to receive management notifications, you must change the broker’s management notification address to start with jms.queue
if it is a JMS Queue or jms.topic
if it is a JMS Topic:
<!-- notifications will be consumed from "notificationsTopic" JMS Topic --> <management-notification-address>jms.topic.notificationsTopic</management-notification-address>
Once the notification topic is created, you can receive messages from it or set a MessageListener
:
Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic"); Session session = ... MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic); notificationConsumer.setMessageListener(new MessageListener() { public void onMessage(Message notif) { System.out.println("------------------------"); System.out.println("Received notification:"); try { Enumeration propertyNames = notif.getPropertyNames(); while (propertyNames.hasMoreElements()) { String propertyName = (String)propertyNames.nextElement(); System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName)); } } catch (JMSException e) { } System.out.println("------------------------"); } });
23.2.8.4. Notification Types and Headers
Below is a list of all the different kinds of notifications as well as which headers are on the messages. Every notification has a _AMQ_NotifType
(value noted in parentheses) and _AMQ_NotifTimestamp
header. The timestamp is the un-formatted result of a call to java.lang.System.currentTimeMillis()
.
BINDING_ADDED
(0)`_AMQ_Binding_Type`, `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Binding_ID`, `_AMQ_Distance`, `_AMQ_FilterString`
BINDING_REMOVED
(1)`_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Binding_ID`, `_AMQ_Distance`, `_AMQ_FilterString`
CONSUMER_CREATED
(2)`_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`, `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`, `_AMQ_SessionName`, `_AMQ_FilterString`
CONSUMER_CLOSED
(3)`_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`, `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`, `_AMQ_SessionName`, `_AMQ_FilterString`
SECURITY_AUTHENTICATION_VIOLATION
(6)`_AMQ_User`
SECURITY_PERMISSION_VIOLATION
(7)`_AMQ_Address`, `_AMQ_CheckType`, `_AMQ_User`
DISCOVERY_GROUP_STARTED
(8)`name`
DISCOVERY_GROUP_STOPPED
(9)`name`
BROADCAST_GROUP_STARTED
(10)`name`
BROADCAST_GROUP_STOPPED
(11)`name`
BRIDGE_STARTED
(12)`name`
BRIDGE_STOPPED
(13)`name`
CLUSTER_CONNECTION_STARTED
(14)`name`
CLUSTER_CONNECTION_STOPPED
(15)`name`
ACCEPTOR_STARTED
(16)`factory`, `id`
ACCEPTOR_STOPPED
(17)`factory`, `id`
PROPOSAL
(18)`_JBM_ProposalGroupId`, `_JBM_ProposalValue`, `_AMQ_Binding_Type`, `_AMQ_Address`, `_AMQ_Distance`
PROPOSAL_RESPONSE
(19)`_JBM_ProposalGroupId`, `_JBM_ProposalValue`, `_JBM_ProposalAltValue`, `_AMQ_Binding_Type`, `_AMQ_Address`, `_AMQ_Distance`
CONSUMER_SLOW
(21)`_AMQ_Address`, `_AMQ_ConsumerCount`, `_AMQ_RemoteAddress`, `_AMQ_ConnectionName`, `_AMQ_ConsumerName`, `_AMQ_SessionName`
23.2.9. Message Counters
Message counters can be used to obtain information on queues over time as the broker keeps a history on queue metrics.
They can be used to show trends on queues. For example, using the management API, it would be possible to query the number of messages in a queue at regular intervals. However, this would not be enough to know if the queue is used: the number of messages can remain constant because nobody is sending or receiving messages from the queue or because there are as many messages sent to the queue than messages consumed from it. The number of messages in the queue remains the same in both cases but its use is widely different.
Message counters gives additional information about the queues:
count
The total number of messages added to the queue since the broker was started
countDelta
The number of messages added to the queue since the last message counter update
messageCount
The current number of messages in the queue
messageCountDelta
The overall number of messages added/removed from the queue since the last message counter update. For example, if
messageCountDelta
is equal to-10
this means that overall 10 messages have been removed from the queue (for example, 2 messages were added and 12 were removed)lastAddTimestamp
The timestamp of the last time a message was added to the queue
udpateTimestamp
The timestamp of the last message counter update
These attributes can be used to determine other meaningful data as well. For example, to know specifically how many messages were consumed from the queue since the last update simply subtract the
messageCountDelta
fromcountDelta
.
23.2.9.1. Configure Message Counters
By default, message counters are disabled as it might have a small negative effect on memory.
To enable message counters, you can set it to true
in broker.xml
:
<message-counter-enabled>true</message-counter-enabled>
Message counters keeps a history of the queue metrics (10 days by default) and samples all the queues at regular interval (10 seconds by default). If message counters are enabled, these values should be configured to suit your messaging use case in broker.xml
:
<!-- keep history for a week --> <message-counter-max-day-history>7</message-counter-max-day-history> <!-- sample the queues every minute (60000ms) --> <message-counter-sample-period>60000</message-counter-sample-period>
Message counters can be retrieved using the Management API. For example, to retrieve message counters on a JMS Queue using JMX:
// retrieve a connection to the brokers MBeanServer MBeanServerConnection mbsc = ... JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc, on, JMSQueueControl.class, false); // message counters are retrieved as a JSON String String counters = queueControl.listMessageCounter(); // use the MessageCounterInfo helper class to manipulate message counters more easily MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters); System.out.format("%s message(s) in the queue (since last sample: %s)\n", messageCounter.getMessageCount(), messageCounter.getMessageCountDelta());