Apache ActiveMQ® is the most popular open source, multi-protocol, Java-based message broker. It is widely used in a lot of multi service application environments where we need to pass messages between services.
All this type of environments (kubernets, docker swarm etc. ) are used to be able to monitor and control the component services using APIs.
Lucky for us ActiveMQ comes bundled with Jolokia which provides a RESTful interface to ActiveMQ’s JMX capabilities.
Once you discover how to make calls to this API ACtiveMQ becomes much more powerful and easier to integrate in environments where monitoring and control using API calls are essential.
The Jolokia API is basically executing operations or interrogating parameters on ActiveMQ MBean objects. ActiveMQ exposes the following MBeans with some attributes and operations that can be executed on them. A very confusing table is available in the official documentation. Click the image for the original source manual page.
So how do we make a call to the API to get the value of an attribute or to execute an operation on a Mbean.
First of all we use as example curl which is easy to integrate in bash scripts but this calls should work from any Internet browser or from any other type of http client implemented in Java or Go or any other language.
Structure of a Jolokia API call:
$baseURL/$callType/org.apache.activemq:$MBeanTypePropertiesOrObjectName/$AttributeOrOperationWhere:
- $baseURL = The default base URL of the Jolokia API deployed on localhost is “http://localhost:8161/api/jolokia/”
- $callType = There are two allowed values “exec” in case we want to perform and operation on a MBean (column 4 from the table) or “read” in case we want to perform a read of an attribute (column 3 from the table)
- $MBeanTypePropertiesOrObjectName = This is the most complex part. Here we actually refer to a MBean of a specific type from column 1 from the table, by giving a fully qualified description as specified in column 2 of the table. It is easier by example. Let us specify for example the DLQ Destination of our localhost broker with the default DLQ queue with name ActiveMQ.DLQ. The destination will be identified according to column 2 as : “type=Broker, brokerName=localhost,destinationType=Queue,destinationName=ActiveMQ.DLQ”
- $AttributeOrOperation = this will specify an attribute (column 3 ) in case $callType = “read” or an operation (column 4) in case of $callType = “exec” that can be read or executed on a given MBean
So now looking at the above let us give two practical examples.
EXAMPLE 1: Return the size of the DLQ. The Jolokia API call will look like:
http://localhost:8161/api/jolokia/read/type=Broker,brokerName=localhost,destinationType=Queue,destinationName=ActiveMQ.DLQ/QueueSizeEXAMPLE 2: Purge the DLQ to empty it. The Jolokia API call will look like:
http://localhost:8161/api/jolokia/exec/type=Broker,brokerName=localhost,destinationType=Queue,destinationName=ActiveMQ.DLQ/purge
EXAMPLE 3: Return the current health status of ActiveMQ. The Jolokia API call will look like:
http://localhost:8161/api/jolokia/read/type=Broker,brokerName=localhost,Service=Health/CurrentStatusSo now if we want to call this from command line using curl for EXAMPLE 1 the call becomes:
curl -XGET --user admin:admin --header "Origin: http://localhost" http://localhost:8161/api/jolokia/read/type=Broker,brokerName=localhost,destinationType=Queue,destinationName=ActiveMQ.DLQ/QueueSizeNote that we need to specify the user/password pair and also the Origin header to have access to the API call.
The above curl call can be easy integrated in any monitoring and control tool of our environment to read attributes and perform some operations if needed.