JMX Management
| Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to 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 for JMX support. The easiest way to configure JMX is to use the default JMX support agent.
This version of Mule uses log4j2, which is configured in the $MULE_HOME/conf/log4j2.xml file. References in this document to log4j no longer are applicable. For more information, see Logging in Mule.
|
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 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.
JMX Server
Attributes of <jmx-server…>
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
server-ref |
string |
no |
The mBean server to use. |
|
locateServer |
boolean |
no |
true |
Whether the agent should try locating an MBeanServer instance before creating one. |
createServer |
boolean |
no |
false |
Whether the agent should create an MBean server if one couldn’t be found or locateServer was set to false. |
createRmiRegistry |
boolean |
no |
true |
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 |
enableStatistics |
boolean |
no |
true |
Whether statistics reporting is enabled for the Mule instance. |
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.
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 | Type | Required | Default | Description |
|---|---|---|---|---|
jmxAdaptorUrl |
string |
no |
The URL of the JMX web console. The default is |
|
login |
string |
no |
The login name for accessing the JMX web console. |
|
password |
string |
no |
The password for accessing the JMX web console. |
|
authenticationMethod |
enumeration |
no |
basic |
The type of authentication to perform when the login and password are set: basic (the default), digest, or none. |
cacheXsl |
string |
no |
true |
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. |
xslFilePath |
string |
no |
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. |
|
pathInJar |
string |
no |
If the xslFilePath is a JAR file, specifies the directory in the JAR where the XSL files are located. |
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 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.
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 />