Creating and Registering a Custom JMX MBean for Apache Geode

4 min readOct 17, 2021

Introduction

Apache Geode provides a collection of JMX MBeans that are useful for monitoring the health of a DistributedSystem.

Each member of the DistributedSystem registers several JMX MBeans including:

The AsyncEventQueueMXBean which provides AsyncEventQueue attributes like the queue size and overflowed entries.
The CacheServerMXBean which provides CacheServer operations like getting client status (e.g. number of gets and puts) and client queue details (e.g. queue size, number of entries queued and removed). It also provides attributes like the number of connected clients and their connections, the operation rates and the number of bytes sent and received.
The DiskStoreMXBean which provides DiskStore attributes like the number of bytes on disk, the disk read and write rates and the queue size for asynchronous DiskStores.
The GatewayReceiverMXBean which provides GatewayReceiver operations like stopping and starting. It also provides attributes like the number of connected GatewaySenders, the operation rates and the number of bytes sent and received.
The GatewaySenderMXBean which provides GatewaySender operations like starting, stopping, pausing and resuming. It also provides attributes like the rate of events received and queued, the queue size (entries and bytes) and the number of batches dispatched.
The MemberMXBean which provides Member operations like getting a list of current threads. It also provides attributes like the number of threads, open file descriptors, process CPU, heap memory (maximum, free and used) and physical memory (total and free).
The RegionMXBean which provides Region attributes like the number of entries and operation rate.

See the documentation here for a full list of DistributedSystem member MBeans, and the documentation here for additional details on the JMX architecture. Any JMX tool (e.g. JConsole or VisualVM) can be used to access these MBeans.

Sometimes, data required for troubleshooting is available via Java API but not via JMX MBean. Apache Geode provides a way to create and register a custom JMX MBean in each DistributedSystem member.

This article describes how to do this.

Implementation

All source code described in this article as well as an example usage is available here.

The IndexMetricsMXBean is a custom MBean interface that provides metrics for an OQL Index including the number of keys, values, uses, updates and locks.

The MBean provides these operations for the Index:

fetchNumKeys — gets the number of keys
fetchNumValues — gets the number of values
fetchNumUses — gets the number of uses
fetchNumUpdates — gets the number of updates
fetchReadLockCount — gets the number of read locks
fetchIndexMetrics — gets all of these values in one IndexMetrics object

The IndexMetricsMBean is the implementation of IndexMetricsMXBean.

The IndexMetrics is a data object that wraps all of the relevant metrics for an Index.

Create and Register the IndexMetricsMBean

The IndexMetricsMBean must be created and registered on the server. There are several ways to do this. One way is to use the initialize method of a CacheListener. The initialize method is called when the CacheListener is created in the server. The IndexMetricsMXBeanInitializer initialize method creates and registers the IndexMetricsMBean.

Operations

Each of the IndexMetricsMBean operations is implemented in a similar manner. Each operation first retrieves the Region, Index and IndexStatistics for the input parameters using getIndexStatistics. It then returns the appropriate value from the IndexStatistics.

The getIndexStatistics method returns the IndexStatistics.

The fetchNumKeys method invokes getIndexStatistics and returns the number of keys.

The fetchIndexMetrics method invokes getIndexStatistics and returns an IndexMetrics object that contains all of the relevant metrics.

Execute Operations

An example of executing the fetchNumKeys operation from JConsole is shown below.

An example of executing the fetchIndexMetrics operation from JConsole is shown below.

Future

A gfsh command to deploy a custom JMX MBean would be a useful addition to Apache Geode. The implementation could be similar to the deploy command for Functions where the custom MBean code would be contained in a jar file that is pushed to each member of the DistributedSystem. The MBean would then be created and registered in each member.