Apache
/
activemq-artemis
mirror of https://github.com/apache/activemq-artemis.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
activemq-artemis/docs/user-manual/en/management.md

1095 lines
40 KiB
Markdown
Raw Normal View History

ACTIVEMQ6-9 - port to markdown https://issues.apache.org/jira/browse/ACTIVEMQ6-9 remove the jboss jdocbook build and style and replace using plane markdown
2014-12-04 10:25:29 -05:00
Management
==========
ActiveMQ has an extensive management API that allows a user to modify a
server configuration, create new resources (e.g. JMS queues and topics),
inspect these resources (e.g. how many messages are currently held in a
queue) and interact with it (e.g. to remove messages from a queue). All
the operations allows a client to *manage* ActiveMQ. It also allows
clients to subscribe to management notifications.
There are 3 ways to manage ActiveMQ:
- Using JMX -- JMX is the standard way to manage Java applications
- Using the core API -- management operations are sent to ActiveMQ
server using *core messages*
- Using the JMS API -- management operations are sent to ActiveMQ
server using *JMS messages*
Although there are 3 different ways to manage ActiveMQ 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.
The Management API
==================
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.
ActiveMQ exposes its managed resources in 2 packages:
- *Core* resources are located in the
`org.apache.activemq.api.core.management` package
- *JMS* resources are located in the
`org.apache.activemq.api.jms.management` package
The way to invoke a *management operations* depends whether JMX, core
messages, or JMS messages are used.
> **Note**
>
> A few management operations requires a `filter` parameter to chose
> which messages are involved by the operation. Passing `null` or an
> empty string means that the management operation will be performed on
> *all messages*.
Core Management API
-------------------
ActiveMQ defines a core management API to manage core resources. For
full details of the API please consult the javadoc. In summary:
### Core Server 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()` or `deployQueue()` or `destroyQueue()`)on
the `ActiveMQServerControl` (with the ObjectName
`org.apache.activemq:module=Core,type=Server` or the resource name
`core.server`)
`createQueue` will fail if the queue already exists while
`deployQueue` 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's resumed, it'll begin delivering the queued messages, if
any.
- Listing and closing remote connections
Client's remote addresses can be retrieved using
`listRemoteAddresses()`. It is also possible to close the
connections associated with a remote address using the
`closeConnectionsForAddress()` method.
Alternatively, connection IDs can be listed using
`listConnectionIDs()` and all the sessions for a given connection ID
can be listed using `listSessions()`.
- Transaction heuristic operations
In case of a server crash, when the server restarts, it it possible
that some transaction requires manual intervention. The
`listPreparedTransactions()` method lists the transactions which are
in the prepared states (the transactions are represented as opaque
Base64 Strings.) To commit or rollback a given prepared transaction,
the `commitPreparedTransaction()` or `rollbackPreparedTransaction()`
method can be used to resolve heuristic transactions. Heuristically
completed transactions can be listed using the
`listHeuristicCommittedTransactions()` and
`listHeuristicRolledBackTransactions` methods.
- Enabling and resetting Message counters
Message counters can be enabled or disabled using the
`enableMessageCounters()` or `disableMessageCounters()` method. To
reset message counters, it is possible to invoke
`resetAllMessageCounters()` and `resetAllMessageCounterHistories()`
methods.
- Retrieving the server configuration and attributes
The `ActiveMQServerControl` exposes ActiveMQ server configuration
through all its attributes (e.g. `getVersion()` method to retrieve
the server's version, etc.)
- Listing, creating and destroying Core bridges and diverts
A list of deployed core bridges (resp. diverts) can be retrieved
using the `getBridgeNames()` (resp. `getDivertNames()`) method.
Core bridges (resp. diverts) can be created or destroyed using the
management operations `createBridge()` and `destroyBridge()` (resp.
`createDivert()` and `destroyDivert()`) on the
`ActiveMQServerControl` (with the ObjectName
`org.apache.activemq:module=Core,type=Server` or the resource name
`core.server`).
- It is possible to stop the server and force failover to occur with
any currently attached clients.
to do this use the `forceFailover()` on the `ActiveMQServerControl`
(with the ObjectName `org.apache.activemq:module=Core,type=Server`
or the resource name `core.server`)
> **Note**
>
> Since this method actually stops the server you will probably
> receive some sort of error depending on which management service
> you use to call it.
### Core Address Management
Core addresses can be managed using the `AddressControl` class (with the
ObjectName `org.apache.activemq:module=Core,type=Address,name="<the
address name>"` or the resource name
`core.address.<the
address name>`).
- Modifying roles and permissions for an address
You can add or remove roles associated to a queue using the
`addRole()` or `removeRole()` methods. You can list all the roles
associated to the queue with the `getRoles()` method
### 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:module=Core,type=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 (e.g. to remove a single message) or a filter (e.g. to expire all
messages with a given property.)
- 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 the `setExpiryAddress()` 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 the
`setDeadLetterAddress()` method.
Messages can also be moved from a queue to another queue by using
the `moveMessages()` method.
- Listing and removing messages
Messages can be listed from a queue by using the `listMessages()`
method which returns an array of `Map`, one `Map` for each message.
Messages can also be removed from the queue by using the
`removeMessages()` method which returns a `boolean` for the single
message ID variant or the number of removed messages for the filter
variant. The `removeMessages()` method takes a `filter` 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, the `countMessages()`
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 a `boolean` 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()` and `listMessageCounterHistory()` methods
(see ?). The message counters can also be reset for a single queue
using the `resetMessageCounter()` method.
- Retrieving the queue attributes
The `QueueControl` exposes Core queue settings through its
attributes (e.g. `getFilter()` to retrieve the queue's filter if it
was created with one, `isDurable()` to know whether the queue is
durable or not, etc.)
- 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's resume, it'll begin delivering the queued messages, if
any.
### Other Core Resources Management
ActiveMQ allows to start and stop its remote resources (acceptors,
diverts, bridges, etc.) so that a server can be taken off line for a
given period of time without stopping it completely (e.g. if other
management operations must be performed such as resolving heuristic
transactions). These resources are:
- Acceptors
They can be started or stopped using the `start()` or. `stop()`
method on the `AcceptorControl` class (with the ObjectName
`org.apache.activemq:module=Core,type=Acceptor,name="<the acceptor
name>"` or the resource name
`core.acceptor.<the
address name>`). The acceptors parameters
can be retrieved using the `AcceptorControl` attributes (see ?)
- Diverts
They can be started or stopped using the `start()` or `stop()`
method on the `DivertControl` class (with the ObjectName
`org.apache.activemq:module=Core,type=Divert,name=<the divert name>`
or the resource name `core.divert.<the divert name>`). Diverts
parameters can be retrieved using the `DivertControl` attributes
(see ?)
- Bridges
They can be started or stopped using the `start()` (resp. `stop()`)
method on the `BridgeControl` class (with the ObjectName
`org.apache.activemq:module=Core,type=Bridge,name="<the bridge
name>"` or the resource name
`core.bridge.<the bridge
name>`). Bridges parameters can be retrieved
using the `BridgeControl` attributes (see ?)
- Broadcast groups
They can be started or stopped using the `start()` or `stop()`
method on the `BroadcastGroupControl` class (with the ObjectName
`org.apache.activemq:module=Core,type=BroadcastGroup,name="<the broadcast group
name>"` or the resource name
`core.broadcastgroup.<the broadcast group name>`). Broadcast groups
parameters can be retrieved using the `BroadcastGroupControl`
attributes (see ?)
- Discovery groups
They can be started or stopped using the `start()` or `stop()`
method on the `DiscoveryGroupControl` class (with the ObjectName
`org.apache.activemq:module=Core,type=DiscoveryGroup,name="<the discovery group
name>"` or the resource name
`core.discovery.<the
discovery group name>`). Discovery groups
parameters can be retrieved using the `DiscoveryGroupControl`
attributes (see ?)
- Cluster connections
They can be started or stopped using the `start()` or `stop()`
method on the `ClusterConnectionControl` class (with the ObjectName
`org.apache.activemq:module=Core,type=ClusterConnection,name="<the cluster
connection name>"` or the resource name
`core.clusterconnection.<the cluster connection name>`). Cluster
connections parameters can be retrieved using the
`ClusterConnectionControl` attributes (see ?)
JMS Management API
------------------
ActiveMQ defines a JMS Management API to manage JMS *administrated
objects* (i.e. JMS queues, topics and connection factories).
### JMS Server Management
JMS Resources (connection factories and destinations) can be created
using the `JMSServerControl` class (with the ObjectName
`org.apache.activemq:module=JMS,type=Server` or the resource name
`jms.server`).
- Listing, creating, destroying connection factories
Names of the deployed connection factories can be retrieved by the
`getConnectionFactoryNames()` method.
JMS connection factories can be created or destroyed using the
`createConnectionFactory()` methods or `destroyConnectionFactory()`
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 (e.g.
`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
first `key` will be associated to the first transport configuration
and the second `key` will be associated to the second transport
configuration (see ? for a list of the transport parameters)
- Listing, creating, destroying queues
Names of the deployed JMS queues can be retrieved by the
`getQueueNames()` method.
JMS queues can be created or destroyed using the `createQueue()`
methods or `destroyQueue()` methods. These queues are bound to JNDI
so that JMS clients can look them up
- Listing, creating/destroying topics
Names of the deployed topics can be retrieved by the
`getTopicNames()` method.
JMS topics can be created or destroyed using the `createTopic()` or
`destroyTopic()` methods. These topics are bound to JNDI so that JMS
clients can look them up
- Listing and closing remote connections
JMS Clients remote addresses can be retrieved using
`listRemoteAddresses()`. It is also possible to close the
connections associated with a remote address using the
`closeConnectionsForAddress()` method.
Alternatively, connection IDs can be listed using
`listConnectionIDs()` and all the sessions for a given connection ID
can be listed using `listSessions()`.
### JMS ConnectionFactory Management
JMS Connection Factories can be managed using the
`ConnectionFactoryControl` class (with the ObjectName
`org.apache.activemq:module=JMS,type=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 (e.g. `getConsumerWindowSize()`
to retrieve the consumer window size for flow control,
`isBlockOnNonDurableSend()` to know whether the producers created
from the connection factory will block or not when sending
non-durable messages, etc.)
### JMS Queue Management
JMS queues can be managed using the `JMSQueueControl` class (with the
ObjectName `org.apache.activemq:module=JMS,type=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 the `setExpiryAddress()` 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 the
`setDeadLetterAddress()` method.
Messages can also be moved from a queue to another queue by using
the `moveMessages()` method.
- Listing and removing messages
Messages can be listed from a queue by using the `listMessages()`
method which returns an array of `Map`, one `Map` for each message.
Messages can also be removed from the queue by using the
`removeMessages()` method which returns a `boolean` for the single
message ID variant or the number of removed messages for the filter
variant. The `removeMessages()` method takes a `filter` 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, the `countMessages()`
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 a `boolean` 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()` and `listMessageCounterHistory()` methods
(see ?)
- Retrieving the queue attributes
The `JMSQueueControl` exposes JMS queue settings through its
attributes (e.g. `isTemporary()` to know whether the queue is
temporary or not, `isDurable()` to know whether the queue is durable
or not, etc.)
- 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.
### JMS Topic Management
JMS Topics can be managed using the `TopicControl` class (with the
ObjectName `org.apache.activemq:module=JMS,type=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
of `Object` representing the subscriptions information (subscription
name, client ID, durability, message count, etc.). It is also
possible to list the JMS messages for a given subscription with the
`listMessagesForSubscription()` 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)
Using Management Via JMX
========================
ActiveMQ can be managed using
[JMX](http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html).
The management API is exposed by ActiveMQ using MBeans interfaces.
ActiveMQ registers its resources with the domain `org.apache.activemq`.
For example, the `ObjectName` to manage a JMS Queue `exampleQueue` is:
org.apache.activemq:module=JMS,type=Queue,name="exampleQueue"
and the MBean is:
org.apache.activemq.api.jms.management.JMSQueueControl
The MBean's `ObjectName` are built using the helper class
`org.apache.activemq.api.core.management.ObjectNameBuilder`. You can
also use `jconsole` to find the `ObjectName` of the MBeans you want to
manage.
Managing ActiveMQ 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.
Configuring JMX
---------------
By default, JMX is enabled to manage ActiveMQ. It can be disabled by
setting `jmx-management-enabled` to `false` in
`activemq-configuration.xml`:
<!-- false to disable JMX management for ActiveMQ -->
<jmx-management-enabled>false</jmx-management-enabled>
If JMX is enabled, ActiveMQ can be managed locally using `jconsole`.
> **Note**
>
> Remote connections to JMX are not enabled by default for security
> reasons. Please refer to [Java Management
> guide](http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html)
> to configure the server for remote management (system properties must
> be set in `run.sh` or `run.bat` scripts).
By default, ActiveMQ server uses the JMX domain "org.apache.activemq".
To manage several ActiveMQ servers from the *same* MBeanServer, the JMX
domain can be configured for each individual ActiveMQ server by setting
`jmx-domain` in `activemq-configuration.xml`:
<!-- use a specific JMX domain for ActiveMQ MBeans -->
<jmx-domain>my.org.apache.activemq</jmx-domain>
### MBeanServer configuration
When ActiveMQ is run in standalone, it uses the Java Virtual Machine's
`Platform MBeanServer` to register its MBeans. This is configured in
JBoss Microcontainer Beans file (see ?):
<!-- MBeanServer -->
<bean name="MBeanServer" class="javax.management.MBeanServer">
<constructor factoryClass="java.lang.management.ManagementFactory"
factoryMethod="getPlatformMBeanServer" />
</bean>
When it is integrated in JBoss AS 5+, it uses the Application Server's
own MBean Server so that it can be managed using AS 5's jmx-console:
<!-- MBeanServer -->
<bean name="MBeanServer" class="javax.management.MBeanServer">
<constructor factoryClass="org.jboss.mx.util.MBeanServerLocator"
factoryMethod="locateJBoss" />
</bean>
Example
-------
See ? for an example which shows how to use a remote connection to JMX
and MBean proxies to manage ActiveMQ.
Using Management Via Core API
=============================
The core management API in ActiveMQ 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 server 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,
ActiveMQ server will handle it, extract the information, invoke the
operation on the managed resources and send a *management 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](http://json.org)
String rather than Java Serialization (the
`org.apache.activemq.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:
1. Create a `ClientRequestor` to send messages to the management
address and receive replies
2. Create a `ClientMessage`
3. Use the helper class
`org.apache.activemq.api.core.management.ManagementHelper` to fill
the message with the management properties
4. Send the message using the `ClientRequestor`
5. Use the helper class
`org.apache.activemq.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(m);
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.api.core.management.ResourceNames` and are
straightforward (`core.queue.exampleQueue` for the Core Queue
`exampleQueue`, `jms.topic.exampleTopic` for the JMS Topic
`exampleTopic`, etc.).
Configuring Core Management
---------------------------
The management address to send management messages is configured in
`activemq-configuration.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 `manage` to
be able to receive and handle management messages. This is also
configured in activemq-configuration.xml:
<!-- users with the admin role will be allowed to manage -->
<!-- ActiveMQ using management messages -->
<security-setting match="jms.queue.activemq.management">
<permission type="manage" roles="admin" />
</security-setting>
Using Management Via JMS
========================
Using JMS messages to manage ActiveMQ 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:
1. create a `QueueRequestor` to send messages to the management address
and receive replies
2. create a `Message`
3. use the helper class
`org.apache.activemq.api.jms.management.JMSManagementHelper` to fill
the message with the management properties
4. send the message using the `QueueRequestor`
5. use the helper class
`org.apache.activemq.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");
Configuring JMS Management
--------------------------
Whether JMS or the core API is used for management, the configuration
steps are the same (see ?).
Example
-------
See ? for an example which shows how to use JMS messages to manage
ActiveMQ server.
Management Notifications
========================
ActiveMQ emits *notifications* to inform listeners of potentially
interesting events (creation of new resources, security violation,
etc.).
These notifications can be received by 3 different ways:
- JMX notifications
- Core messages
- JMS messages
JMX Notifications
-----------------
If JMX is enabled (see ?), JMX notifications can be received by
subscribing to 2 MBeans:
- `org.apache.activemq:module=Core,type=Server` for notifications on
*Core* resources
- `org.apache.activemq:module=JMS,type=Server` for notifications on
*JMS* resources
Core Messages Notifications
---------------------------
ActiveMQ 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, etc.).
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 server.
### Configuring The Core Management Notification Address
The management notification address to receive management notifications
is configured in `activemq-configuration.xml`:
<management-notification-address>activemq.notifications</management-notification-address>
By default, the address is `activemq.notifications`.
JMS Messages Notifications
--------------------------
ActiveMQ's 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 server'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("------------------------");
}
});
Example
-------
See ? for an example which shows how to use a JMS `MessageListener` to
receive management notifications from ActiveMQ server.
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
`_HQ_NotifType` (value noted in parentheses) and `_HQ_NotifTimestamp`
header. The timestamp is the un-formatted result of a call to
`java.lang.System.currentTimeMillis()`.
- `BINDING_ADDED` (0)
`_HQ_Binding_Type`, `_HQ_Address`, `_HQ_ClusterName`,
`_HQ_RoutingName`, `_HQ_Binding_ID`, `_HQ_Distance`,
`_HQ_FilterString`
- `BINDING_REMOVED` (1)
`_HQ_Address`, `_HQ_ClusterName`, `_HQ_RoutingName`,
`_HQ_Binding_ID`, `_HQ_Distance`, `_HQ_FilterString`
- `CONSUMER_CREATED` (2)
`_HQ_Address`, `_HQ_ClusterName`, `_HQ_RoutingName`, `_HQ_Distance`,
`_HQ_ConsumerCount`, `_HQ_User`, `_HQ_RemoteAddress`,
`_HQ_SessionName`, `_HQ_FilterString`
- `CONSUMER_CLOSED` (3)
`_HQ_Address`, `_HQ_ClusterName`, `_HQ_RoutingName`, `_HQ_Distance`,
`_HQ_ConsumerCount`, `_HQ_User`, `_HQ_RemoteAddress`,
`_HQ_SessionName`, `_HQ_FilterString`
- `SECURITY_AUTHENTICATION_VIOLATION` (6)
`_HQ_User`
- `SECURITY_PERMISSION_VIOLATION` (7)
`_HQ_Address`, `_HQ_CheckType`, `_HQ_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`, `_HQ_Binding_Type`,
`_HQ_Address`, `_HQ_Distance`
- `PROPOSAL_RESPONSE` (19)
`_JBM_ProposalGroupId`, `_JBM_ProposalValue`,
`_JBM_ProposalAltValue`, `_HQ_Binding_Type`, `_HQ_Address`,
`_HQ_Distance`
- `CONSUMER_SLOW` (21)
`_HQ_Address`, `_HQ_ConsumerCount`, `_HQ_RemoteAddress`,
`_HQ_ConnectionName`, `_HQ_ConsumerName`, `_HQ_SessionName`
Message Counters
================
Message counters can be used to obtain information on queues *over time*
as ActiveMQ 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 interval. 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 server
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 (e.g. 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`
from `countDelta`.
Configuring 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
`activemq-configuration.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
`activemq-configuration.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 ActiveMQ's 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());
Example
-------
See ? for an example which shows how to use message counters to retrieve
information on a JMS `Queue`.
Administering ActiveMQ Resources Using The JBoss AS Admin Console
=================================================================
Its possible to create and configure ActiveMQ resources via the admin
console within the JBoss Application Server.
The Admin Console will allow you to create destinations (JMS Topics and
Queues) and JMS Connection Factories.
Once logged in to the admin console you will see a JMS Manager item in
the left hand tree. All ActiveMQ resources will be configured via this.
This will have a child items for JMS Queues, Topics and Connection
Factories, clicking on each node will reveal which resources are
currently available. The following sections explain how to create and
configure each resource in turn.
JMS Queues
----------
To create a new JMS Queue click on the JMS Queues item to reveal the
available queues. On the right hand panel you will see an add a new
resource button, click on this and then choose the default(JMS Queue)
template and click continue. The important things to fill in here are
the name of the queue and the JNDI name of the queue. The JNDI name is
what you will use to look up the queue in JNDI from your client. For
most queues this will be the only info you will need to provide as
sensible defaults are provided for the others. You will also see a
security roles section near the bottom. If you do not provide any roles
for this queue then the servers default security configuration will be
used, after you have created the queue these will be shown in the
configuration. All configuration values, except the name and JNDI name,
can be changed via the configuration tab after clicking on the queue in
the admin console. The following section explains these in more detail
After highlighting the configuration you will see the following screen
![ActiveMQ console1.png](images/console1.png)
The name and JNDI name can't be changed, if you want to change these
recreate the queue with the appropriate settings. The rest of the
configuration options, apart from security roles, relate to address
settings for a particular address. The default address settings are
picked up from the servers configuration, if you change any of these
settings or create a queue via the console a new Address Settings entry
will be added. For a full explanation on Address Settings see ?
To delete a queue simply click on the delete button beside the queue
name in the main JMS Queues screen. This will also delete any address
settings or security settings previously created for the queues address
The last part of the configuration options are security roles. If non
are provided on creation then the servers default security settings will
be shown. If these are changed or updated then new security settings are
created for the address of this queue. For more information on security
setting see ?
It is also possible via the metrics tab to view statistics for this
queue. This will show statistics such as message count, consumer count
etc.
Operations can be performed on a queue via the control tab. This will
allow you to start and stop the queue, list,move,expire and delete
messages from the queue and other useful operations. To invoke an
operation click on the button for the operation you want, this will take
you to a screen where you can parameters for the operation can be set.
Once set clicking the ok button will invoke the operation, results
appear at the bottom of the screen.
JMS Topics
----------
Creating and configuring JMS Topics is almost identical to creating
queues. The only difference is that the configuration will be applied to
the queue representing a subscription.
JMS Connection Factories
------------------------
The format for creating connection factories is the same as for JMS
Queues and topics apart from the configuration being different. For as
list of all the connection factory settings see the configuration index