Contact Us 1-800-596-4880

JMX Management

Java Management Extensions (JMX) is a simple and standard way to manage applications, devices, services, and other resources. JMX is dynamic, so you can use it to monitor and manage resources as they are created, installed, and implemented. You can also use JMX to monitor and manage the Java Virtual Machine (JVM).

Each resource is instrumented by one or more Managed Beans, or MBeans. All MBeans are registered in an MBean Server. The JMX server agent consists of an Mbean Server and a set of services for handling Mbeans.

There are several agents provided with Mule ESB for JMX support. The easiest way to configure JMX is to use the default JMX support agent.

Using the Default JMX Support Agent

You can configure several JMX agents simultaneously using the <jmx-default-config> element. When set, this element registers the following agents:

  • JMX agent

  • RMI registry agent (if necessary) on rmi://localhost:1099

  • Remote JMX access on service:jmx:rmi:///jndi/rmi://localhost:1099/server

  • (Optional) Log4J JMX agent, which exposes the configuration of the Log4J instance used by Mule for JMX management

  • JMX notification agent used to receive server notifications using JMX notifications

  • (Optional) MX4J adapter, which provides web-based JMX management, statistics, and configuration viewing of a Mule instance

This element includes the following properties:

xslt: Unexpected program error: java.lang.NullPointerException

For example:

<?xml version="1.0" encoding="UTF-8" ?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:management="http://www.mulesoft.org/schema/mule/management"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/management
http://www.mulesoft.org/schema/mule/management/current/mule-management.xsd">
  <management:jmx-default-config port="1098" registerMx4jAdapter="true">
    <management:credentials>
      <spring:entry key="jsmith" value="foo"/>
      <spring:entry key="dthomas" value="bar"/>
      <spring:entry key="clee" value="pwd"/>
    </management:credentials>
  </management:jmx-default-config>
</mule>

Note: you only need to specify the port if you don’t want to use the default of 1099.

The default agent does a lot of useful plumbing for JMX but at the expense of defaulting many parameters. If you need to customize some subsystems, you could either:

  • Subclass

and override the corresponding createXXX() factory methods.

  • Disassemble the services provided by this support agent into separate agents and configure them individually.

Configuring the JMX Agent

The JMX agent enables the configuration of a local or remote JMX connection to Mule and registers Mule flows with the MBean server. You can then use JMX to view the configuration state of the Mule Manager, stop and start the Mule instance, stop and start flows, stop/start/resume components, and query event processing and endpoint routing statistics on individual flows or the whole server instance.

You configure the JMX agent using the <jmx-server> element. You can set the following properties on the agent.

xslt: Unexpected program error: java.lang.NullPointerException

For example:

<management:jmx-server >
  <management:connector-server url="service:jmx:rmi:///jndi/rmi://localhost:1099/server" rebind="false" />
  <management:credentials>
    <spring:entry key="jsmith" value="foo" />
    <spring:entry key="dthomas" value="bar" />
  </management:credentials>
</management:jmx-server>

Note that the JMX domain for the Mule server is taken from the Mule server ID. To set the server ID, you set the -M-Dmule.serverId=YOUR_MULE_SERVER_ID system property at the command line, or set it programatically by calling org.mule.config.DefaultMuleConfiguration.setId(). You can also set it in your web.xml file as follows:

<context-param>
        <param-name>mule.serverId</param-name>
        <param-value>MyServer</param-value>
</context-param>

Remote Management

You can configure the Mule JMX subsystem for remote management with third-party tools like MC4J. Mule provides an RMI registry agent, which binds to an existing RMI registry or creates a new one on a defined URI.

You configure the RMI registry agent using the <rmi-server> element. This element has two attributes: serverUri, which you set to the URI of the RMI server (the
default is rmi://localhost:1099), and createRegistry, which you set to true if you want to create a new registry instead of binding to an existing one.

For example:

<management:rmi-server serverUri="rmi://myServer.com:1099" createRegistry="true" />

JMX Notifications Agent

The <jmx-notifications> element configures the JMX notifications agent, which sends JMX server notifications. This element takes the following attributes:

Attribute Description

ignoreManagerNotifications

Whether to ignore notifications for state changes on the Mule manager such as initializing, starting, and stopping.

ignoreModelNotifications

Whether to ignore notifications for state changes on models such as models initializing, starting, and stopping or components being registered or unregistered.

ignoreComponentNotifications

Whether to ignore notifications for state changes on components such as when a component is started, stopped, paused, or resumed.

ignoreConnectionNotifications

Whether to ignore notifications when a connector attempts to connect to its underlying resource. Notifications are fired when a connection is made, released, or the connection attempt fails.

ignoreSecurityNotifications

Whether to ignore notifications about security.

ignoreManagementNotifications

Whether to ignore notifications for when a request is denied security access.

ignoreCustomNotifications

Whether to ignore notifications fired by objects to custom notification listeners.

ignoreAdminNotifications

Whether to ignore administrative notifications about requests being received by the Mule Admin agent. These are usually trigged by MuleClient calls using the RemoteDispatcher, which proxies calls to a remote server.

ignoreMessageNotifications

Whether to ignore message notifications. These notifications are fired when an event is sent or received in the system. They are very good for tracing, but they create a performance impact, so they should only be used during testing.

For example:

<management:jmx-notifications ignoreAdminNotifications="true" ignoreMessageNotifications="true" />

Endpoint Notifications Publisher Agent

This agent routes server notifications to a specified endpoint URI. You configure it using the <publish-notifications> element and specify the endpoint using the endpointAddress attribute. For example:

<management:publish-notifications endpointAddress="vm://myService" />

Log4J Agent

The log4j agent exposes the configuration of the Log4J instance used by Mule for JMX management. You enable the Log4J agent using the <jmx-log4j> element. It does not take any additional properties.

For example:

<management:jmx-log4j/>

Log4J Notifications Agent

The Log4J notifications agent logs server notifications to a file or console using Log4J. You configure this agent using the <log4j-notifications> element. It takes the same attributes as the JMX notifications agent plus two additional attributes: logName, a name used to identify this log, and logConfigFile, the name of the file where you want to output the log messages.

The Log4J notifications agent also takes the <level-mapping> child element, which takes one or more pairs of severity/eventId attributes. The severity attribute specifies the severity level of the notifications you want to log for the corresponding event ID. The severity level can be DEBUG, INFO, WARN, ERROR, or FATAL. The eventId attribute specifies the type of event to log. The event ID is the notification type plus the action, such as ModelNotification.stop.

For example:

<management:log4j-notifications logName="myMuleLog" logConfigFile="mule-log.txt">
  <management:level-mapping eventId="ModelNotification.stop" severity="WARN"/>
</management:log4j-notifications>

Chainsaw Notifications Agent

The Chainsaw notifications agent logs server notifications to a Chainsaw console. You configure this agent using the <chainsaw-notifications> element. It takes the same attributes as the JMX notifications agent plus two additional attributes: chainsawHost and {chainsawPort}}, which specify the host name and port of the Chainsaw console.

The Chainsaw notifications agent also takes the <level-mapping> child element, which takes one or more pairs of severity/eventId attributes. The severity attribute specifies the severity level of the notifications you want to send to the Chainsaw console for the corresponding event ID. The severity level can be DEBUG, INFO, WARN, ERROR, or FATAL. The eventId attribute specifies the type of event to send to the Chainsaw console. The event ID is the notification type plus the action, such as ModelNotification.stop.

For example:

<management:chainsaw-notifications chainsawHost="localhost" chainsawPort="20202">
  <management:level-mapping eventId="ModelNotification.stop" severity="WARN"/>
</management:chainsaw-notifications>

MX4J Adapter

MX4J is an open source implementation of the JMX technology. The MX4J agent for Mule configures an MX4J HTTP adapter to provide JMX management, statistics, and configuration viewing of a Mule instance. You configure the MX4J agent using the <jmx-mx4j-adaptor> element.

xslt: Unexpected program error: java.lang.NullPointerException

For example:

<management:jmx-mx4j-adaptor jmxAdaptorUrl="https://myjmxserver.com:9999">
  <management:socketFactoryProperties>
    <spring:entry key="keystore" value="/path/to/keystore" />
    <spring:entry key="storepass" value="storepwd" />
  </management:socketFactoryProperties>
</management:jmx-mx4j-adaptor>

For security’s sake, the management console is accessible from the localhost only. To loosen this restriction, change "localhost" to "0.0.0.0", which allows access from any computer on the LAN. For more information, see the MX4J documentation.

MX4J Security

You can protect the JMX web console with a user name and password. If the login property has been specified, the authentication scheme is applied.

In addition to protecting the console, you can protect the in-transit data using SSL. If the socketFactoryProperties element contains at least one property, the agent switches to HTTPS connections. If this element is omitted from the configuration, the agent will always use HTTP, even if you specify https:// in the jmxAdaptorUrl property.

Viewing Statistics

Mule traps many different statistics about the running state of a server and number of events processed. You can view the Mule statistics report in the JMX Management Console by pointing your browser to http://localhost:9999/ and then clicking on any JMX domain name (except for JMImplementation), or go to the Statistics tab and query the JMX domain for statistics from there.

jmx stats

YourKit Profiler

This agent exposes the YourKit profiler to JMX to provide CPU and memory profiling. To use this agent, you must configure the <yourkit-profiler> element as shown below, and you must install and run the Profiler as described in Profiling Mule.

<management:yourkit-profiler />