Chapter 9. Jolokia JMX

Jolokia tries hard to detect as many MBeanServer as available in a JVM. Beside the always present PlatformMBeanServer many application servers create own MBeanServer which not always can be found with standard mechanisms. Therefore Jolokia comes with so called ServerDetectors for many known brands of applications server. These server detectors know how to find MBeanServer by application server specific means.

The set of available of MBeanServers is detected during startup and kept, except for the Jolokia MBeanServer which can kick in and out at any time. For Jolokia operations, all these MBeanServers are tried according the order given below.

All MBeans contained in all detected MBeanServers are merged to give a single view on the set of available MBeans. For MBeans registered with the same name at different MBeanServers, MBeans registered in later MBeanServers are not visible. These hidden MBeans will never be called on READ, WRITE or EXEC operations. Also, for LIST operations only the meta data of the visible MBeans is returned.

This hiding mechanism is used by @JsonMBean to provide a different view of an MBean for JSR-160 connectors (see below).

With this in place, the following configuration can be used to fire up a Jolokia JVM based agent using the HTTP server which comes with OpenJDK/Oracle JVMs (Version 6 or later).

<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:jolokia="http://www.jolokia.org/jolokia-spring/schema/config"
        xsi:schemaLocation="
       http://www.springframework.org/schema/beans 
             http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.jolokia.org/jolokia-spring/schema/config 
             http://www.jolokia.org/jolokia-spring/schema/config/jolokia-config.xsd
       ">

  <jolokia:agent lookupConfig="false" systemPropertiesMode="never">
    <jolokia:config
            autoStart="true"
            host="0.0.0.0"
            port="8778"
            ....
            />
  </jolokia:agent>
</beans>

There are two directives available: <jolokia:agent> declares a Jolokia server with a configuration as defined in an embedded <jolokia:config> configuration section.

<jolokia:agent> has an attribute lookupConfig. If set to true, externally defined <jolokia:config> sections will be looked up, too and merged with the embedded configuration. A <jolokia:config> has an order attribute, which determines the config merge order: The higher order configs will be merged later and hence will override conflicting parameters. By default, external config lookup is disabled.

The attribute systemPropertiesMode determines, how system properties with a prefix jolokia. can be used as configuration values. There are three modes available:

<jolokia:config> takes as attributes all the configuration parameters for the JVM agent as described in Table 3.6, “JVM agent configuration options”. In addition, the is an extra attribute autoStart which allows for automatically starting the HTTP server during the initialization of the application context. By default this is set to true, so the server starts up automatically by default.

Just in case you don't want to use the Jolokia Spring namespace you can also use plain beans to configure a JVM agent. The following examples shows the example above with only base Spring bean configurations (including an Spring EL expression) :

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans
             http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.springframework.org/schema/context
             http://www.springframework.org/schema/context/spring-context.xsd
       http://www.springframework.org/schema/util
             http://www.springframework.org/schema/util/spring-util.xsd">

  <bean name="server" id="jolokia" class="org.jolokia.jvmagent.spring.SpringJolokiaAgent">
    <property name="lookupConfig" value="false"/>
    <property name="systemPropertiesMode" value="never"/>
    <property name="config">
      <bean class="org.jolokia.jvmagent.spring.SpringJolokiaConfigHolder">
        <property name="config">
          <util:map>
            <entry key="autoStart" value="true"/>
            <entry key="host" value="0.0.0.0"/>
            <entry key="port" value="#{configuration['jmx.jolokiaPort']}"/>
            ...
          </util:map>
        </property>
      </bean>
    </property>
  </bean>

</beans>

This style however is only recommended if there are some issues with the Jolokia spring configuration setup (like using Spring EL expressions in Jolokia versions earlier than 1.2.4). Otherwise, the Jolokia configuration namespace is much easier to read.

With <jolokia:mbean-server> the Jolokia MBeanServer can be specified. This is especially useful for adding it to <context:mbean-export> so that this MBeanServer is used for registering @ManagedResource and @JsonMBean. Remember, MBean registered at the Jolokia MBeanServer never will show up in an JSR-160 client except when annotated with @JsonMBean.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:jolokia="http://www.jolokia.org/jolokia-spring/schema/config"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans
             http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.jolokia.org/jolokia-spring/schema/config
             http://www.jolokia.org/jolokia-spring/schema/config/jolokia-config.xsd
       http://www.springframework.org/schema/context
             http://www.springframework.org/schema/context/spring-context.xsd
       ">

  <context:mbean-export server="jolokiaServer"/>
  <jolokia:mbean-server id="jolokiaServer"/>

</beans>

There is an even simpler way to startup a Jolokia JVM agent with a default setup if you use a variant of the jolokia-spring module with the classifier plugin. This artefact contains a predefined Spring configuration for starting up Jolokia with default values automatically:

<dependency>
  <groupId>org.jolokia</groupId>
  <artifactId>jolokia-spring</artifactId>
  <classifier>plugin</classifier>
  <version>1.1.0</version>
</dependency>    

Beside putting this jar into the classpath (along with its dependencies) the only requirement is, that the Spring application context needs to pickup classpath:META-INF/spring/jolokia.xml. Luckily, many Spring based containers like the Camel Maven Plugin do this automatically for you, nothing has to be configured here. Otherwise this application context path has to be added manually, but in this case it is probably easier to use the non-plugin version (without classifier) and declare the Jolokia server explicitly in an existing Spring configuration file as described above.

By default, the Jolokia agent starts on port 8778 on every IP-Address of the host without security.

The configuration can be tweaked via system properties as described in Table 9.1, “System properties modes”. I.e. the plugin doesn't specify any configuration on its own and uses a systemPropertiesMode of "fallback".

As an alternative, the default settings can be customized by providing a standalone <jolokia:config> somewhere in the Spring application context. An order attribute can be used if multiple config declarations are present: the higher the order, the higher the priority. But then again, instead of using the plugin with an external configuration it is probably better to us an explicite <jolokia:agent> declaration, since you have to add to a Spring configuration file anyway.