Camel JMX

Apache Camel has extensive support for JMX to allow you to monitor and control the Camel managed objects a JMX client.

Using JMX to manage Apache 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 CamelNamingStrategy 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://activemq.apache.org/camel/schema/spring">
  <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://activemq.apache.org/camel/schema/spring">
  <jmxAgent id="agent" disabled="true"/>
    ...
</camelContext>

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://activemq.apache.org/camel/schema/spring">
  <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://activemq.apache.org/camel/schema/spring">
  <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://activemq.apache.org/camel/schema/spring">
  <jmxAgent id="agent" createConnector="true"/>
    ...
</camelContext>

JMX Service URL

The default JMX Service URL has the format:

service:jmx:rmi:///jndi/rmi://localhost:<registryPort>/<serviceUrlPath>

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://activemq.apache.org/camel/schema/spring">
  <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>

Or, by adding a jmxAgent element inside the camelContext element in Spring configuration:

<camelContext id="camel" xmlns="http://activemq.apache.org/camel/schema/spring">
  <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://activemq.apache.org/camel/schema/spring">
  <jmxAgent id="agent" createConnector="true" connectorPort="port number"/>
    ...
</camelContext>

When the connector port option is set, the JMX service URL will become:

service:jmx:rmi://localhost:<connectorPort>/jndi/rmi://localhost:<registryPort>/<serviceUrlPath>

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:

service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi/camel

Using the Apache Camel which Jconsole

 

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

org.apache.camel.jmx.usePlatformMBeanServer

true or false

if is true, Camel JMX agent will use the platformMBeanServer which holds the JVM's memory, cpu and some other management information

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://activemq.apache.org/camel/schema/spring">
  <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