Camel JMX
Apache Camel has extensive support for JMX to allow you to monitor and control the Camel managed objects a JMX client.
Spring Dependency
spring-context.jar, spring-aop.jar, spring-beans.jar, spring-core.jar is needed on the classpath by Camel to be able to use JMX instrumentation. If these .jars is not on the classpath Camel will fallback to non JMX mode. This situation is logged at WARN level using logger name org.apache.camel.impl.DefaultCamelContext.
Using JMX to manage Apache Camel
![]() | Some platforms do not allow access to its platform mbean server
The Oracle OC4J J2EE application server will not allow Camel to access the platform mbean server. You can identify this in the log as Camel will log a WARNING.
xxx xx, xxxx xx:xx:xx xx org.apache.camel.management.InstrumentationLifecycleStrategy onContextStart
WARNING: Could not register CamelContext MBean
java.lang.SecurityException: Unauthorized access from application: xx to MBean: java.lang:type=ClassLoading
at oracle.oc4j.admin.jmx.shared.UserMBeanServer.checkRegisterAccess(UserMBeanServer.java:873)
To resolve this you should disable the JMX agent in Camel, see section Disabling JMX instrumentation agent in Camel |
By default, JMX instrumentation agent is enabled in Camel which means that Camel runtime creates and registers MBean management objects with a MBeanServer instance in the VM. This allows Camel users instantly obtain insights into how Camel routes perform down to the individual processor's level.
The supported types of management objects are endpoint , route, service, and processor. Some of these management objects also expose lifecycle operations in addition to performance counter attributes.
The DefaultManagementNamingStrategy is the default naming strategy which builds object names used for MBean registration. By default, org.apache.camel is the domain name for all object names created by CamelNamingStrategy. The domain name of the MBean object can be configured by Java VM system property:
-Dorg.apache.camel.jmx.mbeanObjectDomainName=your.domain.name
Or, by adding a jmxAgent element inside the camelContext element in Spring configuration:
<camelContext id="camel" xmlns="http:>
<jmxAgent id="agent" mbeanObjectDomainName="your.domain.name"/>
...
</camelContext>
Spring configuration always takes precedence over system properties when they both present. It is true for all of JMX related configurations.
Disabling JMX instrumentation agent in Camel
You can disable JMX instrumentation agent by setting Java VM system property as follow. The property value is treated as boolean.
-Dorg.apache.camel.jmx.disabled=true
Or, by adding a jmxAgent element inside the camelContext element in Spring configuration:
<camelContext id="camel" xmlns="http:>
<jmxAgent id="agent" disabled="true"/>
...
</camelContext>
Or in Camel 2.1 its a bit easier (not having to use JVM system property) if using pure Java as you can disable it as follows:
CamelContext camel = new DefaultCamelContext();
camel.disableJMX();
Locating a MBeanServer in the Java VM
Each CamelContext can have an instance of InstrumentationAgent wrapped insider the InstrumentationLifecycleStrategy. The InstrumentationAgent is the object that interfaces with a MBeanServer to register/unregister Camel MBeans. Multiple CamelContexts/InstrumentationAgents can/should share a MBeanServer. By default, Camel runtime picks the first MBeanServer returned by MBeanServerFactory.findMBeanServer method that matches the default domain name of org.apache.camel. You may want to change the default domain name to match the MBeanServer instance that you are already using in your application. Especially, if your MBeanServer is attached to a JMX connector server, you will not need to create a connector server in Camel.
You can configure the matching default domain name via system property.
-Dorg.apache.camel.jmx.mbeanServerDefaultDomain=<your.domain.name>
Or, by adding a jmxAgent element inside the camelContext element in Spring configuration:
<camelContext id="camel" xmlns="http:>
<jmxAgent id="agent" mbeanServerDefaultDomain="your.domain.name"/>
...
</camelContext>
If no matching MBeanServer can be found, a new one is created and the new MBeanServer's default domain name is set according to the default and configuration as mentioned above.
It is also possible to use the PlatformMBeanServer when it is desirable to manage JVM MBeans by setting the system property. The MBeanServer default domain name configuration is ignored as it is not applicable. Starting in next release (1.5), the default value of usePlatformMBeanServer will be changed to "True". You can set the property to "False" to disable using platform MBean server.
-Dorg.apache.camel.jmx.usePlatformMBeanServer=True
Or, by adding a jmxAgent element inside the camelContext element in Spring configuration:
<camelContext id="camel" xmlns="http:>
<jmxAgent id="agent" usePlatformMBeanServer="true"/>
...
</camelContext>
Creating JMX RMI Connector Server
JMX connector server enables MBeans to be remotely managed by a JMX client such as JConsole. Camel JMX RMI connector server can be optionally turned on by setting system property and the MBeanServer used by Camel is attached to that connector server.
-Dorg.apache.camel.jmx.createRmiConnector=True
Or, by adding a jmxAgent element inside the camelContext element in Spring configuration:
<camelContext id="camel" xmlns="http:>
<jmxAgent id="agent" createConnector="true"/>
...
</camelContext>
JMX Service URL
The default JMX Service URL has the format:
registryPort is the RMI registry port and the default value is 1099.
You can set the RMI registry port by system property.
-Dorg.apache.camel.jmx.rmiConnector.registryPort=<port number>
Or, by adding a jmxAgent element inside the camelContext element in Spring configuration:
<camelContext id="camel" xmlns="http:>
<jmxAgent id="agent" createConnector="true" registryPort="port number"/>
...
</camelContext>
serviceUrlPath is the path name in the URL and the default value is /jmxrmi/camel.
You can set the service URL path by system property.
-Dorg.apache.camel.jmx.serviceUrlPath=<path>
![]() | Setting ManagementAgent settings in Java
In Camel 2.4 onwards you can also set the various options on the ManagementAgent:
context.getManagementStrategy().getManagementAgent().setServiceUrlPath("/foo/bar");
context.getManagementStrategy().getManagementAgent().setRegistryPort(2113);
context.getManagementStrategy().getManagementAgent().setCreateConnector(true);
|
Or, by adding a jmxAgent element inside the camelContext element in Spring configuration:
<camelContext id="camel" xmlns="http:>
<jmxAgent id="agent" createConnector="true" serviceUrlPath="path"/>
...
</camelContext>
By default, RMI server object listens on a dynamically generated port which can be a problem for connection established through a firewall. In such situation, RMI connection port can be explicitly set by the system property.
-Dorg.apache.camel.jmx.rmiConnector.connectorPort=<port number>
Or, by adding a jmxAgent element inside the camelContext element in Spring configuration:
<camelContext id="camel" xmlns="http:>
<jmxAgent id="agent" createConnector="true" connectorPort="port number"/>
...
</camelContext>
When the connector port option is set, the JMX service URL will become:
Using JConsole to monitor Camel
The CamelContext should appear in the list of local connections, if you are running JConsole on the same host as Camel.
To connect to a remote Camel instance, or if the local process does not show up, use Remote Process option, and enter an URL. Here is an example localhost URL:
Using the Apache Camel which Jconsole
![]( "updated version after fix for camel-865")
The SystemProperties for Camel JMX support
| Property Name |
value |
Description |
| org.apache.camel.jmx |
true or false |
if is true , it will enable jmx feature in Camel |
See more system properties in this section below: jmxAgent Properties Reference
How to use authentication with JMX
JMX in the JDK have features for authentication and also for using secure connections over SSL. You have to refer to the SUN documentation how to use this:
JMX inside an Application Server
Tomcat 6
See this page for details about enabling JMX in Tomcat.
In short, modify your catalina.sh (or catalina.bat in Windows) file to set the following options...
set CATALINA_OPTS=-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.port=1099 \
-Dcom.sun.management.jmxremote.ssl=false \
-Dcom.sun.management.jmxremote.authenticate=false
JBoss AS 4
By default JBoss creates its own MBean server. To allow Camel to expose to the same server follow these steps:
1. Tell Camel to use the Platform MBean Server (This defaults to true in Camel 1.5)
<camel:camelContext id="camelContext">
<camel:jmxAgent id="jmxAgent" mbeanObjectDomainName="org.yourname" usePlatformMBeanServer="true" />
</camel:camelContext>
2. Alter your JBoss instance to use the Platform MBean server.
Add the following property to your JAVA_OPTS by editing run.sh or run.conf {{ -Djboss.platform.mbeanserver }} See http://wiki.jboss.org/wiki/JBossMBeansInJConsole
WebSphere
Alter the mbeanServerDefaultDomain to be "WebSphere"
<camel:jmxAgent id="agent" createConnector="true" mbeanObjectDomainName="org.yourname" mbeanServerDefaultDomain="WebSphere"/>
Advanced JMX Configuration
The spring configuration file allows you to configure how Camel is exposed to JMX for management. In some cases, you could specify more information here, like the connector's port or the path name.
Example:
<camelContext id="camel" xmlns="http:>
<jmxAgent id="agent" createConnector="true" registryPort="2000" mbeanServerDefaultDomain="org.apache.camel.test"/>
<route>
<from uri="seda:start"/>
<to uri="mock:result"/>
</route>
</camelContext>
If you wish to change the Java 5 JMX settings you can use various JMX system properties
For example you can enable remote JMX connections to the Sun JMX connector, via setting the following environment variable (using set or export depending on your platform). These settings only configure the Sun JMX connector within Java 1.5+, not the JMX connector that Camel creates by default.
SUNJMX=-Dcom.sun.management.jmxremote=true -Dcom.sun.management.jmxremote.port=1616 \
-Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false
(The SUNJMX environment variable is simple used by the startup script for Camel, as additional startup parameters for the JVM. If you start Camel directly, you'll have to pass these parameters yourself.)
jmxAgent Properties Reference
| Spring property |
System property |
Default Value |
Description |
| id |
|
|
The JMX agent name, and it is not optional |
| usePlatformMBeanServer |
org.apache.camel.jmx.usePlatformMBeanServer |
false, true - Release 1.5 or later |
If true then it will use the plateform MBean server form the JVM |
| mbeanServerDefaultDomain |
org.apache.camel.jmx.mbeanServerDefaultDomain |
org.apache.camel |
The default JMX domain of the MBeanServer |
| mbeanObjectDomainName |
org.apache.camel.jmx.mbeanObjectDomainName |
org.apache.camel |
The JMX domain that all objects names will use |
| createConnector |
org.apache.camel.jmx.createRmiConnect |
false |
If we should create a JMX connector (to allow remote management) for the MBeanServer |
| registryPort |
org.apache.camel.jmx.rmiConnector.registryPort |
1099 |
The port that the JMX RMI registry will use |
| connectorPort |
org.apache.camel.jmx.rmiConnector.connectorPort |
-1 (dynamic) |
The port that the JMX RMI server will use |
| serviceUrlPath |
org.apache.camel.jmx.serviceUrlPath |
/jmxrmi/camel |
The path that JMX connector will be registered under |
| onlyRegisterProcessorWithCustomId |
org.apache.camel.jmx.onlyRegisterProcessorWithCustomId |
false |
Camel 2.0: If this option is enabled then only processors with a custom id set will be registered. This allows you to filer out unwanted processors in the JMX console. |
| statisticsLevel |
|
All |
Camel 2.1: Configures the level for whether performance statistics is enabled for the mbean. See section Configuring level of granularity for performance statistics for more details. |
Configuring whether to register mbeans always, for new routes or just by default
Available as of Camel 2.7
Camel now offers 2 settings to control whether or not to register mbeans
| Option |
Default |
Description |
| registerAlways |
false |
If enabled then mbeans is always registered. |
| registerNewRoutes |
true |
If enabled then adding new routes after CamelContext has been started will also register mbeans from that given route. |
By default Camel registers mbeans for all the routes configured when its starting. The registerNewRoutes option control if mbeans should also be registered if you add new routes thereafter. You can disable this, if you for example add and remove temporary routes where management is not needed.
Be a bit caution to use the registerAlways option when using dynamic EIP patterns such as the Recipient List having unique endpoints. If so then each unique endpoint and its associated services/producers would also be registered. This could potential lead to system degration due the rising number of mbeans in the registry. A MBean is not a light-weight object and thus consume memory.
Registering your own Managed Endpoints
Available as of Camel 2.0
You can decorate your own endpoints with spring managed annotations @ManagedResource to allow to register them in the Camel mbean server and thus access your custom mbeans using JMX.
Notice: in Camel 2.1 we have changed this to apply other than just endpoints but then you need to implement the interface org.apache.camel.spi.ManagementAware as well. More about this later.
For example we have the following custom endpoint where we define some options to be managed:
@ManagedResource(description = "Our custom managed endpoint")
public class CustomEndpoint extends MockEndpoint implements ManagementAware<CustomEndpoint> {
public CustomEndpoint(final String endpointUri, final Component component) {
super(endpointUri, component);
}
public Object getManagedObject(CustomEndpoint object) {
return this;
}
public boolean isSingleton() {
return true;
}
protected String createEndpointUri() {
return "custom";
}
@ManagedAttribute
public String getFoo() {
return "bar";
}
@ManagedAttribute
public String getEndpointUri() {
return super.getEndpointUri();
}
}
Programming your own Managed Services
Available as of Camel 2.1
Camel now offers to use your own mbeans when registering services for management. What that means is for example you can develop a custom Camel component and have it expose mbeans for endpoints, consumers and producers etc. All you need to do is to implement the interface org.apache.camel.spi.ManagementAware and return the managed object Camel should use.
Now before you think oh boys the JMX API is really painful and terrible, then yeah you are right. Lucky for us Spring though too and they created a range of annotations you can use to export management on an existing bean. That means that you often use that and just return this in the getManagedObject from the ManagementAware interface. For an example see the code example above with the CustomEndpoint.
Now in Camel 2.1 you can do this for all the objects that Camel registers for management which are quite a bunch, but not all.
For services which do not implement this ManagementAware interface then Camel will fallback to using default wrappers as defined in the table below:
| Type |
MBean wrapper |
| CamelContext |
ManagedCamelContext |
| Component |
ManagedComponent |
| Endpoint |
ManagedEndpoint |
| Consumer |
ManagedConsumer |
| Producer |
ManagedProducer |
| Route |
ManagedRoute |
| Processor |
ManagedProcessor |
| Tracer |
ManagedTracer |
| Service |
ManagedService |
In addition to that there are some extended wrappers for specialized types such as
| Type |
MBean wrapper |
| ScheduledPollConsumer |
ManagedScheduledPollConsumer |
| BrowsableEndpoint |
ManagedBrowseableEndpoint |
| Throttler |
ManagedThrottler |
| Delayer |
ManagedDelayer |
| SendProcessor |
ManagedSendProcessor |
And in the future we will add additional wrappers for more EIP patterns.
ManagementNamingStrategy
Available as of Camel 2.1
Camel provides a pluggable API for naming strategy by org.apache.camel.spi.ManagementNamingStrategy. A default implementation is used to compute the mbean names that all mbeans are registered with.
ManagementStrategy
Available as of Camel 2.1
Camel now provides a totally pluggable management strategy that allows you to be 100% in control of management. It is a rich interface with many methods for management. Not only for adding and removing managed objects from the mbean server but also event notification is provided as well using the org.apache.camel.spi.EventNotifier API. What it does for example is to easier provide an adapter for other management products. In additional it also allows you to provide more details and features that are provided out of the box at Apache.
Configuring level of granularity for performance statistics
Available as of Camel 2.1
You can now set a pre set level whether performance statistics is enabled or not when Camel start ups. The levels are
- All default - Camel will enable statistics for both routes and processors (fine grained)
- RoutesOnly - Camel will only enable statistics for routes (coarse grained)
- Off - Camel will not enable statistics for any.
At runtime you can always use the management console (such as jconsole) to change on a given route or processor whether its statistics are enabled or not.
![]() | What does statistics enabled mean?
Statistics enabled means that Camel will do fine grained performance statistics for that particular mbean. The statistics you can see are many such as: number of exchanges completed/failed, last/total/mina/max/mean processing time, first/last failed time etc. |
Using Java DSL you set this level by:
context.getManagementStrategy().setSatisticsLevel(ManagementStatisticsLevel.RoutesOnly);
And from Spring DSL you do:
<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
<jmxAgent id="agent" statisticsLevel="RoutesOnly"/>
...
</camelContext>
Which endpoints are registered
In Camel 2.1 onwards only singleton endpoints are registered as the overhead for non singleton will be substantial in cases where thousands or millions of endpoints are used. This can happens when using a Recipient List EIP or from a ProducerTemplate that sends a lot of messages.
Which processors are registered
See this FAQ.
How to use the JMX NotificationListener to listen the camel events?
From Camel 2.4 you can use a customer JMX NotificationListener to listen the camel events.
First you need to set up a JmxNotificationEventNotifier before you start the CamelContext.
notifier = new JmxNotificationEventNotifier();
notifier.setSource("MyCamel");
notifier.setIgnoreCamelContextEvents(true);
notifier.setIgnoreRouteEvents(true);
notifier.setIgnoreServiceEvents(true);
CamelContext context = new DefaultCamelContext(createRegistry());
context.getManagementStrategy().addEventNotifier(notifier);
DefaultManagementNamingStrategy naming = (DefaultManagementNamingStrategy) context.getManagementStrategy().getManagementNamingStrategy();
naming.setHostName("localhost");
naming.setDomainName("org.apache.camel");
Second you can register your listener for listening the event
ObjectName on = ObjectName.getInstance("org.apache.camel:context=localhost/camel-1,type=eventnotifiers,name=JmxEventNotifier");
MyNotificationListener listener = new MyNotificationListener();
context.getManagementStrategy().getManagementAgent().getMBeanServer().addNotificationListener(on,
listener,
new NotificationFilter() {
public boolean isNotificationEnabled(Notification notification) {
return notification.getSource().equals("MyCamel");
}
}, null);
See Also
