Chapter 23. 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

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

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.

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

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.

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>

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.

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)"}

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>

Whether JMS or the core API is used for management, the configuration steps are the same. See Configure Core Management.

If JMX is enabled (see the Configure JMX section), JMX notifications can be received by subscribing to 2 MBeans:

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.

<management-notification-address>activemq.notifications</management-notification-address>

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("------------------------");
   }
});

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().

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());