LibraryPrintFeedback

Managing and Monitoring a Broker

Version 7.1

December 2012
Trademark Disclaimer
Third Party Acknowledgements

Updated: 08 Jan 2014

Revision History

Table of Contents

1. Editing a Broker's Configuration
Understanding the Fuse MQ Enterprise Configuration Model
Editing a Standalone Broker's Configuration
Editing a Broker's Configuration in a Fabric
2. Setting up and Accessing the Fuse MQ Enterprise Web Console
Using the Embedded Console
Securing the Web Console
Deploying a Standalone Console
3. Deploying a New Broker Instance
4. Using Logging
Logging Configuration
Viewing the Log
5. Using JMX
Configuring JMX
Statistics Collected by JMX
Managing the Broker with JMX
Index

List of Figures

1.1. Fuse MQ Enterprise Configuration System

List of Tables

5.1. Broker JMX Configuration Properties
5.2. Broker JMX Statistics
5.3. Destination JMX Statistics
5.4. Connection JMX Statistics
5.5. Broker MBean Operations
5.6. Connector MBean Operations
5.7. Network Connector MBean Operations
5.8. Queue MBean Operations
5.9. Topic MBean Operations
5.10. Subscription MBean Operations

List of Examples

1.1. Adding Property Placeholder Support to Fuse MQ Enterprise Configuration
1.2. Configuration with Property Placeholders
1.3. Importing an XML Configuration Template
1.4. Creating a Profile Using an XML Configuration Template
1.5. Creating a Deployment Profile
1.6. Setting Properties in a Profile
1.7. Setting the Broker Name Property
1.8. Assigning a Profile to a Broker
2.1. Changing the Web Console's Port
2.2. SSL Enabled Web Console Configuration
2.3. Disabling the Embedded Web Console
2.4. Configuration for Deploying the Web Console in Tomcat
2.5. Configuration for Monitoring a Cluster with the Web Console
3.1. Specifying a Broker's Template XML Configuration
3.2. Uploading a Template to a Fabric Ensemble
3.3. Creating a New Broker in an Existing Container
3.4. Creating a New Broker in a New Container
3.5. Editing a Broker Profile
4.1. Changing Logging Levels
4.2. Changing the Log Information Displayed on the Console
5.1. Configuring a Broker's JMX Connection

Configuring a broker involves making changes to a number of properties that are stored in multiple locations including:

  • an XML configuration file

  • OSGi persistent identifier properties

How you make the changes depends on how the broker is deployed:

  • standalone—if a broker is deployed as a standalone entity and not a part of a fabric, you change the configuration using a combination of directly editing the broker's configuration template file and the console's config shell.

  • in a fabric—if a broker is deployed into a fabric its configuration is managed by the Fabric Agent which draws all of the configuration from the fabric's registry. To modify the container of a broker running as part of a fabric, you need to modify the profile(s) deployed into it. You can do this by using either the fabric:profile-edit console command or Fuse Management Console.

[Note]Note

Many of the configuration properties are managed by the OSGi Admin Service and are organized by persistent identifier or PID. The container services look in a specific PID for particular properties, so it is important to set the properties in the correct PID.

The Fuse MQ Enterprise configuration template is an XML file that is based on the Apache ActiveMQ configuration file. The main differences between an Apache ActiveMQ and a Fuse MQ Enterprise configuration template are:

  • configuration templates use property placeholders for settings that will be controlled via the OSGi Admin service

  • configuration templates do not configure the broker's name

  • configuration templates do not configure the location of the data directory

  • configuration templates do not configure transport connectors

  • configuration templates do not configure network connectors

  • configuration templates do not control if a broker is a master or a slave node

  • configuration templates can be used as a baseline for multiple brokers on the same machine

The networking properties and role in a master/slave group are specified by the broker's PID and do not need to appear in the template. The broker's name and data directory are replaced in the template with property placeholders. Property placeholders can also be substituted for any attribute value or element value in the XML configuration. This allows the OSGi Admin system populate them from the broker's PID.

Property placeholders are specified using the syntax ${propName} and are resolved by matching properties in the broker's PID. In order to use property placeholder the configuration template must include the bean definition shown in Example 1.1.


The configuration template shown in Example 1.2 uses three property placeholders that allow you to modify the base configuration using fabric properties.


The default broker configuration template is etc/activemq.xml. You can the location of the configuration template by changing the config property in the broker's etc/org.fusesource.mq.fabric.server-default.cfg file.

The template can be edited using any text or XML editor.

The broker must be restarted for any changes in the template to take effect.

The recommended approach to configuring brokers in a fabric is:

  1. Create a configuration template.

  2. Create a base profile for all of the brokers in the fabric using the configuration template.

  3. Create profiles that inherit from the base profile that will be assigned to one or more brokers.

  4. Modify the properties in each of the profiles to the desired values for the brokers to which the profile will be assigned.

  5. Assign the new profiles to the desired brokers.

You should always create new profiles or a new version of the existing profiles before making configuration changes. Changes to profiles that are assigned to running brokers take effect immediately. Using new profiles, or a new version, allows you make the changes and test them on a subset of your brokers before rolling the changes to the entire fabric.

The Fuse MQ Enterprise Web console is an embedded console for administering standalone broker. Using the embedded console is an easy way to manage your broker with minimal configuration.

[Note]Note

For monitoring a broker hosted in a Fabric container, use Fuse Management Console. The Fuse MQ Enterprise Web console does not work in a Fabric container.

If you want more security, more reliability, or the ability to monitor master/slave clusters, you can deploy the Web console as a standalone application. It is easy to deploy into Tomcat or any standard Web container.

For a standalone broker the default configuration is for the Web console to be loaded along with the broker. The default address for the standalone broker's console is localhost:8181/activemqweb.

[Note]Note

When a broker is deployed into a fabric, the default configuration profile does not include the Web console. The Fuse MQ Enterprise Web console does not work in a Fabric container, so to achieve similar functionality you can use Fuse Management Console

The default port and security configuration can easily be modified.

To enable SSL security on the Jetty server, edit the Connector bean in the conf/jetty.xml file. Replace the org.eclipse.jetty.server.nio.SelectChannelConnector class with the org.eclipse.jetty.server.ssl.SslSelectChannelConnector class. Specify the relevant properties of the SslSelectChannelConnector class in order to configure the Jetty server's HTTPS port as shown in Example 2.2.


The SslSelectChannelConnector properties can be explained as follows:

When SSL security is configured as shown, you can access the Web console through the HTTPS protocol using the URL https://localhost:8443/admin.

[Warning]Warning

The broker.ks certificate used in the example is insecure. Anyone can access its private key. To secure your system properly, you must create new certificates signed by a trusted CA, as described in Managing Certificates in ActiveMQ Security Guide.

To deploy a new broker into an Fuse ESB Enterprise container in a fabric:

  1. Create a template Apache ActiveMQ XML configuration file in a location that is accessible to the container.

  2. In the Fuse ESB Enterprise command console, use the fabric:import command to upload the your XML configuration template to the Fabric Ensemble as shown in Example 3.2.


    version must match the version of the new profile you will create for the new broker.

  3. Use the fabric:mq-create command to create a profile for the new broker and assign it to a container.

    [Tip]Tip

    You can add network configuration settings to the profile as well. See fabric:mq-create in Console Reference.

  4. Use the fabric:profile-edit command shown in Example 3.5 to set the required properties.


    The properties that need to be set will depend on the properties you specified using property place holders in the template XML configuration and the broker's network settings.

    For information on using fabric:profile-edit see fabric:profile-edit in Console Reference.

[Tip]Tip

If you want to simply deploy a second broker that uses the default configuration template skip Step 1 and Step 2.

[Tip]Tip

Fuse Management Console makes this process easier by providing a Web based UI.

Fuse MQ Enterprise uses the OPS4j Pax Logging system. Pax Logging is an open source OSGi logging service that extends the standard OSGi logging service to make it more appropriate for use in enterprise applications. It uses Apache Log4j as the back-end logging service. Pax Logging has its own API, but it also supports the following APIs:

  • Apache Log4j

  • Apache Commons Logging

  • SLF4J

  • Java Util Logging

By default Fuse MQ Enterprise creates MBeans, loads them into the MBean server created by the JVM, and creates a dedicated JMX connector that provides a Fuse MQ Enterprise-specific view of the MBean server. The default settings are sufficient for simple deployments and make it easy to access the statistics and management operations provided by a broker. For more complex deployments you easily configure many aspects of how a broker configures itself for access through JMX. For example, you can change the JMX URI of the JMX connector created by the broker or force the broker to use the generic JMX connector created by the JVM.

By connecting a JMX aware management and monitoring tool to a broker's JMX connector, you can view detailed information about the broker. This information provides a good indication of broker health and potential problem areas. In addition to the collected statistics, Fuse MQ Enterprise's JMX interface provides a number of operations that make it easy to manage a broker instance. These include stopping a broker, starting and stopping network connectors, and managing destinations.

If the default JMX behavior is not appropriate for your deployment environment, you can customize how the broker exposes its MBeans. To customize a broker's JMX configuration, you add a managementContext child element to the broker's broker element. The managementContext element uses a managementContext child to configure the broker. The attributes of the inner managementContext element specify the broker's JMX configuration.

Table 5.1 describes the configuration properties for controlling a broker's JMX behavior.


Example 5.1 shows configuration for a broker that will only use the JVM's MBean server and will not create its own JMX connector.


Table 5.3 describes the statistics collected for a destination.

Table 5.3. Destination JMX Statistics

NameDescription
BlockedProducerWarningIntervalSpecifies, in milliseconds, the interval between warnings issued when a producer is blocked from adding messages to the destination.
MemoryLimitSpecifies the memory limit, in bytes, used for holding undelivered messages before paging to temporary storage.
MemoryPercentageUsedSpecifies the percentage of available memory in use.
MaxPageSizeSpecifies the maximum number of messages that can be paged into the destination.
CursorFullSpecifies if the cursor has reached its memory limit for paged messages.
CursorMemoryUsageSpecifies, in bytes, the amount of memory the cursor is using.
CursorPercentUsageSpecifies the percentage of the cursor's available memory is in use.
EnqueueCountSpecifies the number of messages that have been sent to the destination.
DequeueCountSpecifies the number of messages that have been acknowledged and removed from the destination.
DispatchCountSpecifies the number of messages that have been delivered to consumers, but not necessarily acknowledged by the consumer.
InFlightCountSpecifies the number of dispatched to, but not acknowledged by, consumers.
ExpiredCountSpecifies the number of messages that have expired in the destination.
ConsumerCountSpecifies the number of consumers that are subscribed to the destination.
QueueSizeSpecifies the number of messages in the destination that are waiting to be consumed.
AverageEnqueueTimeSpecifies the average amount of time, in milliseconds, that messages sat in the destination before being consumed.
MaxEnqueueTimeSpecifies the longest amount of time, in milliseconds, that a message sat in the destination before being consumed.
MinEnqueueTimeSpecifies the shortest amount of time, in milliseconds, that a message sat in the destination before being consumed.
MemoryUsagePortionSpecifies the portion of the broker's memory limit used by the destination.
ProducerCountSpecifies the number of producers connected to the destination.

Table 5.5 describes the operations exposed by the MBean for a broker.

Table 5.5. Broker MBean Operations

OperationDescription
void start(); Starts the broker. In reality this operation is not useful because you cannot access the MBeans if the broker is stopped.
void stop(); Forces a broker to shut down. There is no guarantee that all messages will be properly recorded in the persistent store.
void stopGracefully(String queueName); Checks that all listed queues are empty before shutting down the broker.
void enableStatistics(); Activates the broker's statistics plug-in.
void resetStatistics(); Resets the data collected by the statistics plug-in.
void disableStatistics(); Deactivates the broker's statistics plug-in.
String addConnector(String URI); Adds a transport connector to the broker and starts it listening for incoming client connections and returns the name of the connector.
boolean removeConnector(String connectorName); Deactivates the specified transport connector and removes it from the broker.
String addNetworkConnector(String URI); Adds a network connector to the specified broker and returns the name of the connector.
boolean removeNetworkConnector(String connectorName); Deactivates the specified connector and removes it from the broker.
void addTopic(String name); Adds a topic destination to the broker.
void addQueue(String name); Adds a queue destination to the broker.
void removeTopic(String name); Removes the specified topic destination from the broker.
void removeQueue(String name); Removes the specified queue destination from the broker.
ObjectName createDurableSubscriber(String clientId,
                                   String subscriberId,
                                   String topicName,
                                   String selector);
Creates a new durable subscriber.
void destroyDurableSubscriber(String clientId,
                              String subscriberId);
Destroys a durable subscriber.
void gc(); Runs the JVM garbage cleaner.
void terminateJVM(int exitCode); Shuts down the JVM.
void reloadLog4jProperties(); Reloads the logging configuration from log4j.properties.

Table 5.8 describes the operations exposed by the MBean for a queue destination.

Table 5.8. Queue MBean Operations

OperationDescription
CompositeData getMessage(String messageId); Returns the specified message from the queue without moving the message cursor.
void purge(); Deletes all of the messages from the queue.
boolean removeMessage(String messageId); Deletes the specified message from the queue.
int removeMatchingMessages(String selector); Deletes the messages matching the selector from the queue and returns the number of messages deleted.
int removeMatchingMessages(String selector,
                           int maxMessages);
Deletes up to the maximum number of messages that match the selector and returns the number of messages deleted.
boolean copyMessageTo(String messageId,
                      String destination);
Copies the specified message to a new destination.
int copyMatchingMessagesTo(String selector,
                           String destination);
Copies the messages matching the selector and returns the number of messages copied.
int copyMatchingMessagesTo(String selector,
                           String destination,
                           int maxMessages);
Copies up to the maximum number of messages that match the selector and returns the number of messages copied.
boolean moveMessageTo(String messageId,
                      String destination);
Moves the specified message to a new destination.
int moveMatchingMessagesTo(String selector,
                           String destination);
Moves the messages matching the selector and returns the number of messages moved.
int moveMatchingMessagesTo(String selector,
                           String destination,
                           int maxMessages);
Moves up to the maximum number of messages that match the selector and returns the number of messages moved.
boolean retryMessage(String messageId); Moves the specified message back to its original destination.
int cursorSize(); Returns the number of messages available to be paged in by the cursor.
boolean doesCursorHaveMessagesBuffered(); Returns true if the cursor has buffered messages to be delivered.
boolean doesCursorHaveSpace(); Returns true if the cursor has memory space available.
CompositeData[] browse(); Returns all messages in the queue, without changing the cursor, as an array.
CompositeData[] browse(String selector); Returns all messages in the queue that match the selector, without changing the cursor, as an array.
TabularData browseAsTable(String selector); Returns all messages in the queue that match the selector, without changing the cursor, as a table.
TabularData browseAsTable(); Returns all messages in the queue, without changing the cursor, as a table.
void resetStatistics(); Resets the statistics collected for the queue.
java.util.List browseMessages(String selector); Returns all messages in the queue that match the selector, without changing the cursor, as a list.
java.util.List browseMessages(); Returns all messages in the queue, without changing the cursor, as a list.
String sendTextMessage(String body,
                       String username,
                       String password);
Send a text message to a secure queue.
String sendTextMessage(String body); Send a text message to a queue.

B

BlockedProducerWarningInterval, Destination statistics
broker
addConnector, Broker actions
addNetworkConnector, Broker actions
addQueue, Broker actions
addTopic, Broker actions
createDurableSubscriber, Broker actions
deploying
fabric container, Fabric containers
standalone container, Standalone containers
destroyDurableSubscriber, Broker actions
disableStatistics, Broker actions
enableStatistics, Broker actions
gc, Broker actions
reloadLog4jProperties, Broker actions
removeConnector, Broker actions
removeNetworkConnector, Broker actions
removeQueue, Broker actions
removeTopic, Broker actions
resetStatistics, Broker actions
start, Broker actions
stop, Broker actions
stopGracefully, Broker actions
terminateJVM, Broker actions
useJmx, Enabling and disabling
BrokerId, Broker statistics
BrokerName, Broker statistics
BrokerVersion, Broker statistics

C

config shell, Editing the OSGi properties, Standalone containers
config.properties, Overview
configuration
persistent identifier, OSGi PIDs
PID, OSGi PIDs
template, Configuration templates
connector
connectionCount, Connector actions
disableStatistics, Connector actions
enableStatistics, Connector actions
resetStatistics, Connector actions
start, Connector actions
stop, Connector actions
connectorHost, Advanced configuration
connectorPath, Advanced configuration
connectorPort, Advanced configuration
console
config shell, Editing the OSGi properties
ConsumerCount, Destination statistics
createConnector, Advanced configuration
createMBeanServer, Advanced configuration
CursorFull, Destination statistics
CursorMemoryUsage, Destination statistics
CursorPercentUsage, Destination statistics

D

DataDirectory, Broker statistics
DequeueCount, Destination statistics
DequeueCounter, Subscription statistics
DispatchCount, Destination statistics
DispatchedCounter, Subscription statistics
DispatchedQueueSize, Subscription statistics

E

embedded console
disabling, Disabling the embedded console
EnqueueCount, Destination statistics
EnqueueCounter, Subscription statistics
ExpiredCount, Destination statistics

F

fabric
profiles, Profiles
versions, Profiles
fabric shell, Fabric containers
fabric:mq-create, Fabric containers

I

InFlightCount, Destination statistics

M

managementContext, Advanced configuration
connectorHost, Advanced configuration
connectorPath, Advanced configuration
connectorPort, Advanced configuration
createConnector, Advanced configuration
createMBeanServer, Advanced configuration
jmxDomainName, Advanced configuration
rmiServerPort, Advanced configuration
useMBeanServer, Advanced configuration
MaxEnqueueTime, Destination statistics
MaximumPendingMessageLimit, Subscription statistics
MaxPageSize, Destination statistics
MemoryLimit, Broker statistics, Destination statistics
MemoryPercentageUsed, Broker statistics, Destination statistics
MemoryUsagePortion, Destination statistics
MessageCountAwaitingAcknowledge, Subscription statistics
MinEnqueueTime, Destination statistics
mq-create, Fabric containers

O

org.apache.karaf.log, Overview
org.ops4j.pax.logging, Overview
org.ops4j.pax.logging.DefaultServiceLog.level, Overview
OSGi configuration
creating, Standalone containers

P

PendingQueueSize, Subscription statistics
persistent identifier, OSGi PIDs
PID, OSGi PIDs
PrefetchSize, Subscription statistics
ProducerCount, Destination statistics
profile
creating, Fabric containers

Q

queue
browse, Queue actions
browseAsTable, Queue actions
browseMessages, Queue actions
copyMatchingMessagesTo, Queue actions
copyMessageTo, Queue actions
cursorSize, Queue actions
doesCursorHaveMessagesBuffered, Queue actions
doesCursorHaveSpace, Queue actions
getMessage, Queue actions
moveMatchingMessagesTo, Queue actions
moveMessageTo, Queue actions
purge, Queue actions
removeMatchingMessages, Queue actions
removeMessage, Queue actions
resetStatistics, Queue actions
retryMessage, Queue actions
sendTextMessage, Queue actions
QueueSize, Destination statistics

R

rmiServerPort, Advanced configuration
roles
JMX, Securing access to JMX
routing console
securing, Securing the console

S

SslSelectChannelConnector, Enabling SSL security
standalone broker
configuration template, Editing the configuration template
runtime configuration, Editing the OSGi properties
StoreLimit, Broker statistics
StorePercentageUsed, Broker statistics
subscription
browse, Subscription actions
browseAsTable, Subscription actions
cursorSize, Subscription actions
destory, Subscription actions
doesCursorHaveMessagesBuffered, Subscription actions
doesCursorHaveSpace, Subscription actions
isMatchingQueue, Subscription actions
isMatchingTopic, Subscription actions

T

TempLimit, Broker statistics
TempPercentageUsed, Broker statistics
topic
browse, Topic actions
browseAsTable, Topic actions
browseMessages, Topic actions
resetStatistics, Topic actions
sendTextMessage, Topic actions
TotalConsumerCount, Broker statistics
TotalDequeueCount, Broker statistics
TotalEnqueueCount, Broker statistics
TotalMessageCount, Broker statistics
TotalProducerCount, Broker statistics

W

Web console
accessing, Accessing the console
basic authentication, Enabling basic authentication
clusters, Monitoring clusters
port number, Changing the port
roles, Editing user credentials
securing, Securing the console
SSL, Enabling SSL security
user credentials, Editing user credentials
webconsole.jms.url, Configuring Tomcat, Monitoring clusters
webconsole.jmx.password, Configuring Tomcat
webconsole.jmx.url, Configuring Tomcat, Monitoring clusters
webconsole.jmx.user, Configuring Tomcat