JMX support for JGroups

In 2.2.9, JMX support was added to JGroups. There were several design goals:

- No dependencies on JMX if JMX support is not required. It should be possible to ship a JGroups version without any

JMX support, and without jmxri.jar (for JDK 1.4.x). Therefore channels and protocols are not turned into MBeans, e.g.

FD doesn't implement FDMBean. Instead, a parallel MBean and MBeanImpl hierarchy was created, where the MBeanImpl

delegates to the real protocol. This hierarchy is located in package org.jgroups.jmx.

For a protocol org.jgroups.protocols.P, there is a corresponding org.jgroups.jmx.protocols.PMBean

MBean and an implementation org.jgroups.jmx.protocols.P

- No negative effect on performance, minimal effect on memory. JMX support can be disabled in the channel, and

all protocols (stats="false")

- Support for running in a pre-JMX JDK (1.4, for example), e.g. under JBoss. There is a jgroups-service target in

the ANT build which generates a jgroups-service.sar that can be deployed into JBoss. The channel defines in the

META-INF/jboss-service.xml file of the SAR defines a JGroups channel MBean, which will automatically create MBeans

for all protocols and register them with the MBeanServer

- Support for running in JDK 5 standalone. JDK 5 has JMX support built in. The jconsole tool can be used to inspect the

MBean hierarchy.

To programmatically create MBean support for JDK 5, the following code can be used:

JChannel channel;
channel.connect(groupname);
ArrayList servers=MBeanServerFactory.findMBeanServer(null);
if(servers == null || servers.size() == 0) {
    throw new Exception("No MBeanServers found;" +
                        "\nJmxTest needs to be run with an MBeanServer present, or inside JDK 5");
}
MBeanServer server=(MBeanServer)servers.get(0);
JmxConfigurator.registerChannel(channel, server, "JGroups:channel=" + channel.getChannelName() , true);

JmxConfigurator has a number of helper methods which register and de-register the channel and/or te protocols

attached to a given channel.

Provided information

Some information provided includes (all info can be reset), besides configuration:

• UDP: messages sent/received, bytes sent/received (per member)

• Discovery: manual triggering of discovery

• NAKACK: retransmissions per member, last N retransmitted messages,

  lowest and highest sequence numbers per member

• GMS: membership, history of views

• FD/FD_SOCK: last N suspected members

• STATE_TRANSFER: number of state requests, total bytes transferred

• STABLE: manual triggering of STABLE protocol

Annotations

Starting with JGroups release 2.7 all jmx information is exposed dynamically through a use of Java annotation mechanism.

Previous method of jmx support used in releases 2.2.9 up to 2.7 has been deprecated and removed as use of annotations

provides a much simpler and easier development and maintenance. There are three basic annotation: @MBean, @ManagedAttribute and @ManagedOperation. Developers of custom protocols may use these annotations in order to expose their protocols to jmx agents.

@MBean is an optional annotation that exposes all public methods in the class hierarchy (excluding Object)

as MBean operations. If a more fine grained MBean attribute and operation exposure is needed do not use @MBean

annotation but annotate fields and public methods directly using @ManagedOperation and @ManagedAttribute

annotations.

@MBeanAttribute indicates that a public method or a field (any visibility) in an MBean class defines an MBean

attribute. This annotation can be applied to either a field or a public setter and/or getter method of a public

class that is itself is optionally annotated with an @MBean annotation, or inherits such an annotation from a

superclass.

@MBeanOperation indicates that a method in an MBean class defines an MBean operation.

Example

The Draw program was modified to support JMX. The following steps describe how to configure and run a JDK 5 VM and

look at the resulting Draw application via jconsole.

• Run the Draw program (the JDK needs to be 5 !):

  java -Dcom.sun.management.jmxremote org.jgroups.demos.Draw -props c:\fc-fast.xml -jmx

  (the -jmx flag enables registering the Channel and protocols with the MBeanServer)

• Start jconsole and connect to the local Draw process

• Under 'MBeans', choose the JGroups channel and browse the channel and the protocols

• Optional Add the STATS protocol to the top of the stack; it display information about messages sent

  and received

The following snapshot shows jconsole in action:

!jmx.png!