Menu Search

5.3. JMX Management

5.3.1. Introduction

The JMX management plugin provides a series of managed beans (MBeans) allowing you to control and monitor the Broker via an industry compliant interface. This provides a convenient intergration point for a variety of Infrastructure Monitoring Solutions, tools such as Jconsole and VisualVM, as well as custom Java programs and scripts.

The following sections describe how to connect to JMX, the configuration of the JMX plugin covering topis including securing with SSL, programmatically interacting with Qpid MBeans and finally a summary of all the MBeans made available from by the plugin.

Important

For new development work, the reader is directed towards the strategic Web Management Console and the REST API. Use the Web/REST interfaces in preference to JMX whenever possible. The JMX interface may be withdrawn in a future release.

5.3.2. Default Configuration

By default, the Broker is shipped with JMX enabled.

The RMI registry port runs on port 8999 and the JMX connector on port 9099. The connector is not SSL protected. Qpid will use the Platform MBeanServer.

To change these settings, use the Web Management interface.

5.3.3. Connecting to JMX

The following example uses Jconsole to illustrates how to connect to JMX and assume the defaults described above. Jconsole is a management tool that comes with the JDK. It provides a very simple view of the MBeans, but requires no special configuration to be used with Qpid.

For full details of Jconsole itself refer to Oracle's JConsole Guide.

Jconsole can be used to connect to local or remote Java processes. On startup, it presents a list of all the Java processes running on the local host and also allows you to specify a service url to connect to a Java process running on a remote host.

To start Jconsole on the command line, type:

jconsole

5.3.3.1. Local

To connect to a Broker running locally, simply select the process from the list. You can identify the Broker by looking for its classname org.apache.qpid.server.Main.

5.3.3.2. Remote

To connect to a broker running remotely, provide the hostname and port number of the RMI registry port (e.g. hostname:8999) and a valid username and password.

You can also provide a service url in the form service:jmx:rmi:///jndi/rmi://hostname:8999/jmxrmi

Figure 5.1. Making a remote JMX connection to a Broker using jconsole

Making a remote JMX connection to a Broker using jconsole

Once you are connected expand the tree of nodes marked org.apache.qpid to begin to interact with the Qpid MBeans.

Figure 5.2. Qpid MBean hierarchy

Qpid MBean hierarchy

5.3.3.3. Connecting to a remote Broker protected by SSL

If you are connecting to a remote Broker whose JMX connector port has been secured with SSL certificate signed by a private CA (or a self-signed certificate), you will need to pass a trust store and trust store password to Jconsole. If this is required, start jconsole with the following options:

jconsole -J-Djavax.net.ssl.trustStore=jmxtruststore.jks -J-Djavax.net.ssl.trustStorePassword=password

5.3.4. Example JMX Client

The following java snippet illustrates a JMX client that connects to Qpid over JMX passing a userid and password, looks up the ManagedBroker object corresponding to the myvhost virtualhost, then invokes a method on the virtualhost to create a new queue.

A full introduction to custom JMX clients is beyond the scope of this book. For this the reader is directed toward Oracle's JMX tutorial.

Example 5.4. JMX Client illustrating the creation of a new queue

Map<String, Object< environment = new HashMap<String, Object>();
environment.put(JMXConnector.CREDENTIALS, new String[] {"admin","password"});
// Connect to service
JMXServiceURL url =  new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi");
JMXConnector jmxConnector = JMXConnectorFactory.connect(url, environment);
MBeanServerConnection mbsc =  jmxConnector.getMBeanServerConnection();
// Object name for ManagedBroker mbean for virtualhost myvhost
ObjectName objectName = new ObjectName("org.apache.qpid:type=VirtualHost.VirtualHostManager,VirtualHost=\"myvhost\"");
// Get the ManagedBroker object
ManagedBroker managedBroker = JMX.newMBeanProxy(mbsc, objectName, ManagedBroker.class);;

// Create the queue named "myqueue"
managedBroker.createNewQueue("myqueue", null, true);

The Qpid classes required for a custom JMX client are included in the qpid-management-common artefact.

5.3.5. The MBeans

The following table summarises the available MBeans. The MBeans are self-describing: each attribute and operation carry a description describing their purpose. This description is visible when using tools such Jconsole. They are also available on Management interfaces themselves (linked below).

Table 5.3. Qpid Broker MBeans

Management InterfaceObject Name

ManagedBroker

org.apache.qpid:type=VirtualHost.VirtualHostManager,VirtualHost="virtualhostname"

MBean corresponding to the named virtualhost. Allows operations such as the creation/deletion of queues and exchanges on that virtualhost and virtualhost levell statistics.

ManagedQueue

org.apache.qpid:type=VirtualHost.Queue,VirtualHost="virtualhostname",name="queuename"

MBean corresponding to the named queue on the given virtualhost. Allows queue management operations such as view message, move message and clear queue. Exposes attributes such as queue depth and durability.

ManagedExchange

org.apache.qpid:type=VirtualHost.Exchange,VirtualHost="virtualhostname",name="amq.direct",ExchangeType=type

MBean corresponding to the named exchange on the given virtualhost. Allows exchange management operations such as the creation and removal of bindings. The supported exchange types are exposed by the exchangeTypes attribute of the virtualhost.

ManagedConnection

org.apache.qpid:type=VirtualHost.Connection,VirtualHost="virtualhostname",name="/peerid:ephemeralport"

MBean representing a active AMQP connection to the named virtual host. Name is formed from the IP and ephemeral port of the peer. Attributes include the client version and connection level statistics.

UserManagement

org.apache.qpid:type=UserManagement,name="UserManagement-authentication manager name"

When using Plain password provider or Base 64 MD5 password provider, permits user operations such creation and deletion of users. and password changes.

ServerInformation

org.apache.qpid:type=ServerInformation,name=ServerInformation

Exposes broker wide statistics, product version number and JMX management API version number.

LoggingManagement

org.apache.qpid:type=LoggingManagement,name=LoggingManagement

MBean permitting control of the Broker's logging. Exposes operations allow the logging level to be controlled at runtime (without restarting the Broker) and others that allow changes to be written back to the log4j.xml logging configuration file, or the contents of the log4.xml file to be re-read at runtime.