JMX

Camel has optional support for JMX management which are part of the camel-management and camel-management-api JARs.

Using JMX to manage Apache Camel

By default (requires camel-management JAR to be included in the classpath), 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 to instantly obtain insights into how Camel routes perform down to the individual processor level.

The high level supported types of management objects are:

Most of these management objects also expose lifecycle operations in addition to performance counter attributes.

Disabling or enabling Camel JMX

Camel is only using JMX if camel-management is on the classpath. So a quick way to enable or disable JMX is to either include or exclude this JAR on the classpath.

Its also possible to enable or disable JMX via configuration as documented in the following.

You can disable JMX instrumentation agent by setting the Java VM system property as follows:

-Dorg.apache.camel.jmx.disabled=true

The property value is treated as boolean.

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

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
  <jmxAgent id="agent" disabled="true"/>
    ...
</camelContext>

In Java you can disable JMX directly on the CamelContext as follows:

CamelContext camel = new DefaultCamelContext();
camel.disableJMX();

Camel JMX configuration options

The Camel JMX can be configured with the following options.

Option JVM System Property Default Value Description

id

required The JMX agent name

usePlatformMBeanServer

org.apache.camel.jmx.usePlatformMBeanServer

true

Whether to use the MBeanServer from 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 object names will use

onlyRegisterProcessorWithCustomId

org.apache.camel.jmx.onlyRegisterProcessorWithCustomId

false

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

Default

Configures the level for whether performance statistics is enabled for the MBean. See section Configuring level of granularity for performance statistics for more details.

includeHostName

org.apache.camel.jmx.includeHostName

false

Whether to include the hostname in the MBean naming.

useHostIPAddress

org.apache.camel.jmx.useHostIPAddress

false

Whether to use hostname or IP Address in the service url when creating the remote connector. By default the hostname will be used.

loadStatisticsEnabled

org.apache.camel.jmx.loadStatisticsEnabled

false

Whether load statistics is enabled (gathers load statistics using a background thread per CamelContext).

endpointRuntimeStatisticsEnabled

org.apache.camel.jmx.endpointRuntimeStatisticsEnabled

true

Whether endpoint runtime statistics is enabled (gathers runtime usage of each incoming and outgoing endpoints).

mask

org.apache.camel.jmx.mask

true

A flag that indicates whether to remove detected sensitive information (such as passwords) from MBean names and attributes.

Registering new MBeans for new routes or endpoints

Camel provides two settings to control when 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 careful 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 potentially lead to system degradation due the rising number of mbeans in the registry. A MBean is not a light-weight object and consumes memory.

Management naming pattern

You can configure a naming pattern for the MBeans names that Camel creates. The pattern is used as part of the ObjectName as they key after the domain name.

By default Camel will use MBean names for the ManagedCamelContextMBean as follows:

org.apache.camel:context=camel-1,type=context,name=camel-1

If you configure a name on the CamelContext then that name is part of the ObjectName as well. For example if we have:

<camelContext id="myCamel" ...>

Then the MBean names will be as follows:

org.apache.camel:context=myCamel,type=context,name=myCamel

Now if there is a naming clash in the JVM, such as there already exists a MBean with that given name above, then Camel will by default try to auto-correct this by finding a new free name in the JMXMBeanServer by using a counter. As shown below the counter is now appended, so we have myCamel-1 as part of the ObjectName:

org.apache.camel:context=myCamel-1,type=context,name=myCamel

Naming Patterns

This is possible because Camel uses a naming pattern by default that supports the following tokens:

  • camelId = the CamelContext id (eg the name)

  • name - same as camelId

  • counter - an incrementing counter

  • bundleId - the OSGi bundle id (only for OSGi environments)

  • symbolicName - the OSGi symbolic name (only for OSGi environments)

  • version - the OSGi bundle version (only for OSGi environments)

The default naming pattern is differentiated between OSGi and non-OSGi as follows:

  • non OSGI: name

  • OSGi: symbolicName

If there is a naming clash in the JMXMBeanServer then Camel will automatic fallback and use the counter in the pattern to remedy this. And thus the following patterns will then be used:

  • non OSGI: name-counter

  • OSGi: symbolicName-counter

If you set an explicit naming pattern, then that pattern is always used, and the default patterns above is not used.

This allows us to have full control, very easily, of the naming for both the CamelContext id in the Registry as well the JMX MBeans in the JMXMBeanRegistry.

So if we want to explicit name both the CamelContext and to use fixed MBean names, that do not change (eg has no counters), then we can use the managementNamePattern attribute:

<camelContext id="myCamel" managementNamePattern="#name#">

Then the MBean names will always be as follows:

org.apache.camel:context=myCamel,type=context,name=myCamel

In Java, you can configure the managementNamePattern as follows:

context.getManagementNameStrategy().setNamePattern("#name#");

Configuring performance statistics

You can set a level whether performance statistics is enabled or not when Camel starts up. The levels are:

  • Extended - As default but with additional statistics gathered during runtime such as fine grained level of usage of endpoints and more.

  • `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 use any statistics.

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 the statistics level by:

// only enable routes when Camel starts
context.getManagementStrategy().setStatisticsLevel(ManagementStatisticsLevel.RoutesOnly);

And from XML DSL you can do:

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <jmxAgent id="agent" statisticsLevel="RoutesOnly"/>
 ...
</camelContext>

Performance load statistics

It is possible to include load statistics per CamelContext and Route MBeans. The statistics is average load based on the number of in-flight exchanges, on a per 1, 5, and 15 minute rate. This is similar to load statistics on Unix systems.

You can enable this by setting loadStatisticsEnabled=true.

Hiding sensitive information

By default, Camel enlists MBeans in JMX such as endpoints configured using URIs. In this configuration, there may be sensitive information such as passwords.

This will mask URIs having options such as password and passphrase, and use xxxxxx as the replacement value.

Masking JMX attributes in custom components

When implementing custom Camel components you can mark which JMX attributes to mask with the @ManagedAttribute and @ManagedOperation annotations.

Te attribute mask can be set to true to indicate that the result of this JMX attribute/operation should be masked (if enabled on JMX agent, see above).

For example, on the default managed endpoints from camel-core org.apache.camel.api.management.mbean.ManagedEndpointMBean, we have declared that the EndpointUri JMX attribute is masked:

@ManagedAttribute(description = "Endpoint URI", mask = true)
String getEndpointUri();
Back to top