Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.7)
  3. Developing
  4. Advanced Usage of Mule ESB
  5. Mule Agents

  6. JMX Management

JMX Management

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

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:

Jmx default config

Attributes of <jmx-default-config…​>

Name Type Required Default Description

registerMx4jAdapter

boolean

no

Whether to enable the MX4J adaptor.

registerLog4j

boolean

no

Whether to enable the Log4j agent.

host

string

no

DEPRECATED: The host attribute for jmx-default-config is deprecated, for multi-homed hosts consider using instead the Java system property java.rmi.server.hostname. The host to bind to. Normally, override this only for multi-NIC servers (default is localhost).

port

port number

no

The port on which the RMI registry will run. This is also used for remote JMX management. Default is 1099.

jmxAuthenticator-ref

string

no

A reference to a custom jmxAuthenticator.

Child Elements of <jmx-default-config…​>

Name Cardinality Description

credentials

0..1

A map of username/password properties for remote JMX access. The configuration option delegates to the JmxAgent.

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 - DefaultJmxSupportAgent - This overrides 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.

JMX Server

Attributes of <jmx-server…​>

Name Description

server-ref

The mBean server to use.

Type: string
Required: no
Default: none

locateServer

Whether the agent should try locating an MBeanServer instance before creating one.

Type: boolean
Required: no
Default: true

createServer

Whether the agent should create an MBean server if one couldn’t be found or locateServer was set to false.

Type: boolean
Required: no
Default: false

createRmiRegistry

Whether the agent should try locating an RmiRegistry instance before creating one. Unless there is a RmiRegistry explicitly created on the port defined by the connector-server URI, this must be set to true which is the default.

Type: boolean
Required: no
Default: true

enableStatistics

Whether statistics reporting is enabled for the Mule instance.

Type: boolean
Required: no
Default: true

Child Elements of <jmx-server…​>

Name Cardinality Description

connector-server

0..1

Configures the remote JMX connector server by specifying the URL and whether to rebind.

credentials

0..1

A map of username/password entries used to authenticate remote JMX access. If not specified, remote access is not restricted.

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.

Note: Mule 3.7 and newer uses log4j2, which you configure using the log4j2.xml file.

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.

JMX MX4J Adaptor

Attributes of <jmx-mx4j-adaptor…​>

Name Description

jmxAdaptorUrl

The URL of the JMX web console. The default is http://localhost:9999.

Type: string
Required: no
Default: none

login

The login name for accessing the JMX web console.

Type: string
Required: no
Default: none

password

The password for accessing the JMX web console.

Type: string
Required: no
Default: none

authenticationMethod

The type of authentication to perform when the login and password are set: basic (the default), digest, or none.

Type: enumeration
Required: no
Default: basic

cacheXsl

Indicates whether to cache the transformation objects, which speeds-up the process. It is usually set to true, but you can set it to false for easier testing.

Type: string
Required: no
Default: true

xslFilePath

Specifies the path of the XSL files used to customize the adaptor’s stylesheet. If you specify a directory, it assumes that XSL files are located in the directory. If you specify a .jar or .zip file, it assumes that the files are located inside. Specifying a file system is especially useful for testing.

Type: string
Required: no
Default: none

pathInJar

If the xslFilePath is a JAR file, specifies the directory in the JAR where the XSL files are located.

Type: string
Required: no
Default: none

No Child Elements of <jmx-mx4j-adaptor…​>

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 always uses 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 />