Modified: websites/production/camel/content/camel-jmx.html ============================================================================== --- websites/production/camel/content/camel-jmx.html (original) +++ websites/production/camel/content/camel-jmx.html Sun Jul 26 08:19:49 2015 @@ -207,7 +207,7 @@ java.lang.SecurityException: Unauthorize <script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[SUNJMX=-Dcom.sun.management.jmxremote=true -Dcom.sun.management.jmxremote.port=1616 \ -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false ]]></script> -</div></div><p>(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.)</p><h4 id="CamelJMX-jmxAgentPropertiesReference">jmxAgent Properties Reference</h4><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Spring property</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>System property</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default Value</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>id</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The JMX agent name, and it is not optional</p></td></tr><tr> <td colspan="1" rowspan="1" class="confluenceTd"><p><code>usePlatformMBeanServer</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.usePlatformMBeanServer</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code>, <code>true</code> - Release 1.5 or later</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>If <code>true</code>, it will use the <code>MBeanServer</code> from the JVM</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>mbeanServerDefaultDomain</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.mbeanServerDefaultDomain</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The default JMX domain of the <code>MBeanServer</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>mbeanObjectDomainName</code>< /p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.mbeanObjectDomainName</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The JMX domain that all object names will use</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>createConnector</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.createRmiConnect</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>If we should create a JMX connector (to allow remote management) for the <code>MBeanServer</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>registryPort</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.rmiConnector.registryPort</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>1099</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The port that the JMX RMI registry will use</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>connectorPort</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.rmiConnector.connectorPort</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>-1 (dynamic)</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The port that the JMX RMI server will use</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>serviceUrlPath</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.serviceUrlPath</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>/jmxrmi/camel</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The path that JMX connector will be registered under</p></td></tr><tr><td colspan="1" rowspan= "1" class="confluenceTd"><p><code>onlyRegisterProcessorWithCustomId</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.onlyRegisterProcessorWithCustomId</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.0:</strong> 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.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>statisticsLevel</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>All</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.1:</strong> Configures the level for whether performance statistics is enabled for the MBean. See section <em>Configuring level of granularity for perfo rmance statistics</em> for more details.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>includeHostName</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.includeHostName</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.13:</strong> Whether to include the hostname in the MBean naming. From Camel 2.13 onwards this is default <code>false</code>, where as in older releases its default <code>true</code>. You can use this option to restore old behavior if really needed.</p></td></tr></tbody></table></div><h4 id="CamelJMX-ConfiguringwhethertoregisterMBeansalways,fornewroutesorjustbydefault">Configuring whether to register MBeans always, for new routes or just by default</h4><p><strong>Available as of Camel 2.7</strong></p><p>Camel now offers 2 settings to control whether or not to register mbeans</p><div class="table-wr ap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>registerAlways</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>If enabled then MBeans is always registered.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>registerNewRoutes</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>If enabled then adding new routes after <a shape="rect" href="camelcontext.html">CamelContext</a> has been started will also register MBeans from that given route.</p></td></tr></tbody></table></div><p>By default Camel registers MBea ns for all the routes configured when its starting. The <code>registerNewRoutes</code> 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.</p><p>Be a bit caution to use the <code>registerAlways</code> option when using dynamic <a shape="rect" href="eip.html">EIP</a> patterns such as the <a shape="rect" href="recipient-list.html">Recipient List</a> 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 consumes memory.</p><h3 id="CamelJMX-MonitoringCamelusingJMX">Monitoring Camel using JMX</h3><h4 id="CamelJMX-UsingJConsoletomonitorCamel">Using JConsole to monitor Camel</h4><p>The <code>CamelContext</code> should appear in the list of local conn ections, if you are running JConsole on the same host as Camel.</p><p>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</p><p>Using the Apache Camel with JConsole</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-content-image-border" src="camel-jmx.data/camel-jmx.png" data-image-src="/confluence/download/attachments/85697/camel-jmx.png?version=1&modificationDate=1224680681000&api=v2" data-unresolved-comment-count="0" data-linked-resource-id="9224" data-linked-resource-version="1" data-linked-resource-type="attachment" data-linked-resource-default-alias="camel-jmx.png" data-base-url="https://cwiki.apache.org/confluence"; data-linked-resource-content-type="image/png" data-linked-resource-container-id="85697" data-linked-resource-container-version="75"></span></p ><h4 id="CamelJMX-Whichendpointsareregistered">Which endpoints are >registered</h4><p>In <strong>Camel 2.1</strong> onwards <strong>only</strong> ><code>singleton</code> 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 <a shape="rect" >href="recipient-list.html">Recipient List</a> EIP or from a ><code>ProducerTemplate</code> that sends a lot of messages.</p><h4 >id="CamelJMX-Whichprocessorsareregistered">Which processors are >registered</h4><p>See <a shape="rect" >href="why-is-my-processor-not-showing-up-in-jconsole.html">this >FAQ</a>.</p><h4 >id="CamelJMX-HowtousetheJMXNotificationListenertolistenthecamelevents?">How >to use the JMX NotificationListener to listen the camel events?</h4><p>The >Camel notification events give a coarse grained overview what is happening. >You can see lifecycle event from context and endpoints and you can see >exchanges being received by and sent to endpoints.</p><p>From <strong>Camel 2.4</strong> you can use a custom JMX NotificationListener to listen the camel events.<br clear="none"> First you need to set up a JmxNotificationEventNotifier before you start the CamelContext.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>(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.)</p><h4 id="CamelJMX-jmxAgentPropertiesReference">jmxAgent Properties Reference</h4><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Spring property</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>System property</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default Value</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>id</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The JMX agent name, and it is not optional</p></td></tr><tr> <td colspan="1" rowspan="1" class="confluenceTd"><p><code>usePlatformMBeanServer</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.usePlatformMBeanServer</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code>, <code>true</code> - Release 1.5 or later</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>If <code>true</code>, it will use the <code>MBeanServer</code> from the JVM</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>mbeanServerDefaultDomain</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.mbeanServerDefaultDomain</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The default JMX domain of the <code>MBeanServer</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>mbeanObjectDomainName</code>< /p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.mbeanObjectDomainName</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The JMX domain that all object names will use</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>createConnector</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.createRmiConnect</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>If we should create a JMX connector (to allow remote management) for the <code>MBeanServer</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>registryPort</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.rmiConnector.registryPort</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>1099</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The port that the JMX RMI registry will use</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>connectorPort</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.rmiConnector.connectorPort</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>-1 (dynamic)</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The port that the JMX RMI server will use</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>serviceUrlPath</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.serviceUrlPath</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>/jmxrmi/camel</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The path that JMX connector will be registered under</p></td></tr><tr><td colspan="1" rowspan= "1" class="confluenceTd"><p><code>onlyRegisterProcessorWithCustomId</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.onlyRegisterProcessorWithCustomId</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.0:</strong> 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.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>statisticsLevel</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>All / Default</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.1:</strong> Configures the level for whether performance statistics is enabled for the MBean. See section <em>Configuring level of granularity for performance statistics</em> for more details. From <strong>Camel 2.16</strong> onwards the All option is renamed to Default, and a new Extended option has been introduced which allows gathered additional runtime JMX metrics.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>includeHostName</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.camel.jmx.includeHostName</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.13:</strong> Whether to include the hostname in the MBean naming. From Camel 2.13 onwards this is default <code>false</code>, where as in older releases its default <code>true</code>. You can use this option to restore old behavior if really needed.</p></td></tr></tbody></table></div><h4 id="CamelJMX-ConfiguringwhethertoregisterMBeansalways,fornewroutesorjustbydefault">Configuring whether to register MBeans alway s, for new routes or just by default</h4><p><strong>Available as of Camel 2.7</strong></p><p>Camel now offers 2 settings to control whether or not to register mbeans</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>registerAlways</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>If enabled then MBeans is always registered.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>registerNewRoutes</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>If enabled then adding new routes after <a s hape="rect" href="camelcontext.html">CamelContext</a> has been started will also register MBeans from that given route.</p></td></tr></tbody></table></div><p>By default Camel registers MBeans for all the routes configured when its starting. The <code>registerNewRoutes</code> 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.</p><p>Be a bit caution to use the <code>registerAlways</code> option when using dynamic <a shape="rect" href="eip.html">EIP</a> patterns such as the <a shape="rect" href="recipient-list.html">Recipient List</a> 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 consumes memory.</p><h3 id="CamelJMX-MonitoringCamelusingJ MX">Monitoring Camel using JMX</h3><h4 id="CamelJMX-UsingJConsoletomonitorCamel">Using JConsole to monitor Camel</h4><p>The <code>CamelContext</code> should appear in the list of local connections, if you are running JConsole on the same host as Camel.</p><p>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</p><p>Using the Apache Camel with JConsole</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-content-image-border" src="camel-jmx.data/camel-jmx.png" data-image-src="/confluence/download/attachments/85697/camel-jmx.png?version=1&modificationDate=1224680681000&api=v2" data-unresolved-comment-count="0" data-linked-resource-id="9224" data-linked-resource-version="1" data-linked-resource-type="attachment" data-linked-resource-default-alias="camel-jmx.png" data- base-url="https://cwiki.apache.org/confluence"; data-linked-resource-content-type="image/png" data-linked-resource-container-id="85697" data-linked-resource-container-version="77"></span></p><h4 id="CamelJMX-Whichendpointsareregistered">Which endpoints are registered</h4><p>In <strong>Camel 2.1</strong> onwards <strong>only</strong> <code>singleton</code> 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 <a shape="rect" href="recipient-list.html">Recipient List</a> EIP or from a <code>ProducerTemplate</code> that sends a lot of messages.</p><h4 id="CamelJMX-Whichprocessorsareregistered">Which processors are registered</h4><p>See <a shape="rect" href="why-is-my-processor-not-showing-up-in-jconsole.html">this FAQ</a>.</p><h4 id="CamelJMX-HowtousetheJMXNotificationListenertolistenthecamelevents?">How to use the JMX NotificationListener to listen the camel events?</h4><p >The Camel notification events give a coarse grained overview what is >happening. You can see lifecycle event from context and endpoints and you can >see exchanges being received by and sent to endpoints.</p><p>From ><strong>Camel 2.4</strong> you can use a custom JMX NotificationListener to >listen the camel events.<br clear="none"> First you need to set up a >JmxNotificationEventNotifier before you start the CamelContext.</p><div >class="code panel pdl" style="border-width: 1px;"><div class="codeContent >panelContent pdl"> <script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ // Set up the JmxNotificationEventNotifier notifier = new JmxNotificationEventNotifier(); @@ -224,7 +224,7 @@ DefaultManagementNamingStrategy naming = naming.setHostName("localhost"); naming.setDomainName("org.apache.camel"); ]]></script> -</div></div><p>Second you can register your listener for listening the event</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div>Second you can register your listener for listening the event<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ // register the NotificationListener ObjectName on = ObjectName.getInstance("org.apache.camel:context=localhost/camel-1,type=eventnotifiers,name=JmxEventNotifier"); @@ -240,7 +240,7 @@ context.getManagementStrategy().getManag }, null); ]]></script> -</div></div><h4 id="CamelJMX-UsingtheTracerMBeantogetfinegrainedtracing">Using the Tracer MBean to get fine grained tracing</h4><p>Additionally to the coarse grained notifications above <strong>Camel 2.9.0</strong> support JMX Notification for fine grained trace events.<br clear="none"> These can be found in the Tracer MBean. To activate fine grained tracing you first need to activate tracing on the context or on a route.<br clear="none"> This can either be done when configuring the context or on the context / route MBeans.</p><p>As a second step you have to set the <code>jmxTraceNotifications</code> attribute to <code>true</code> on the tracer. This can again be done when configuring the context or at runtime on the tracer MBean.</p><p>Now you can register for TraceEvent Notifications on the Tracer MBean using JConsole. There will be one Notification for every step on the route with all exchange and message details.</p><p><span class="confluence-embedded-file-wrapper"><img class="c onfluence-embedded-image confluence-content-image-border" src="camel-jmx.data/jconsole_trace_notifications.png" data-image-src="/confluence/download/attachments/85697/jconsole_trace_notifications.png?version=1&modificationDate=1317961747000&api=v2" data-unresolved-comment-count="0" data-linked-resource-id="28016788" data-linked-resource-version="1" data-linked-resource-type="attachment" data-linked-resource-default-alias="jconsole_trace_notifications.png" data-base-url="https://cwiki.apache.org/confluence"; data-linked-resource-content-type="image/png" data-linked-resource-container-id="85697" data-linked-resource-container-version="75"></span></p><h3 id="CamelJMX-UsingJMXforyourownCamelCode">Using JMX for your own Camel Code</h3><h4 id="CamelJMX-RegisteringyourownManagedEndpoints">Registering your own Managed Endpoints</h4><p><strong>Available as of Camel 2.0</strong><br clear="none"> You can decorate your own endpoints with Spring managed annotations <code>@ManagedResource< /code> to allow to register them in the Camel <code>MBeanServer</code> and thus access your custom MBeans using JMX.<br clear="none"> <strong>Notice:</strong> in <strong>Camel 2.1</strong> we have changed this to apply other than just endpoints but then you need to implement the interface <code>org.apache.camel.spi.ManagementAware</code> as well. More about this later.</p><p>For example we have the following custom endpoint where we define some options to be managed:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><h4 id="CamelJMX-UsingtheTracerMBeantogetfinegrainedtracing">Using the Tracer MBean to get fine grained tracing</h4><p>Additionally to the coarse grained notifications above <strong>Camel 2.9.0</strong> support JMX Notification for fine grained trace events.<br clear="none"> These can be found in the Tracer MBean. To activate fine grained tracing you first need to activate tracing on the context or on a route.<br clear="none"> This can either be done when configuring the context or on the context / route MBeans.</p><p>As a second step you have to set the <code>jmxTraceNotifications</code> attribute to <code>true</code> on the tracer. This can again be done when configuring the context or at runtime on the tracer MBean.</p><p>Now you can register for TraceEvent Notifications on the Tracer MBean using JConsole. There will be one Notification for every step on the route with all exchange and message details.</p><p><span class="confluence-embedded-file-wrapper"><img class="c onfluence-embedded-image confluence-content-image-border" src="camel-jmx.data/jconsole_trace_notifications.png" data-image-src="/confluence/download/attachments/85697/jconsole_trace_notifications.png?version=1&modificationDate=1317961747000&api=v2" data-unresolved-comment-count="0" data-linked-resource-id="28016788" data-linked-resource-version="1" data-linked-resource-type="attachment" data-linked-resource-default-alias="jconsole_trace_notifications.png" data-base-url="https://cwiki.apache.org/confluence"; data-linked-resource-content-type="image/png" data-linked-resource-container-id="85697" data-linked-resource-container-version="77"></span></p><h3 id="CamelJMX-UsingJMXforyourownCamelCode">Using JMX for your own Camel Code</h3><h4 id="CamelJMX-RegisteringyourownManagedEndpoints">Registering your own Managed Endpoints</h4><p><strong>Available as of Camel 2.0</strong><br clear="none"> You can decorate your own endpoints with Spring managed annotations <code>@ManagedResource< /code> to allow to register them in the Camel <code>MBeanServer</code> and thus access your custom MBeans using JMX.<br clear="none"> <strong>Notice:</strong> in <strong>Camel 2.1</strong> we have changed this to apply other than just endpoints but then you need to implement the interface <code>org.apache.camel.spi.ManagementAware</code> as well. More about this later.</p><p>For example we have the following custom endpoint where we define some options to be managed:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ @ManagedResource(description = "Our custom managed endpoint") public class CustomEndpoint extends MockEndpoint implements ManagementAware<CustomEndpoint> { @@ -272,7 +272,7 @@ public class CustomEndpoint extends Mock } } ]]></script> -</div></div><p>Notice from <strong>Camel 2.9</strong> onwards its encouraged to use the <code>@ManagedResource</code>, <code>@ManagedAttribute</code>, and <code>@ManagedOperation</code> from the <code>org.apache.camel.api.management</code> package. This allows your custom code to not depend on Spring JARs.</p><h4 id="CamelJMX-ProgrammingyourownManagedServices">Programming your own Managed Services</h4><p><strong>Available as of Camel 2.1</strong></p><p>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 <code>org.apache.camel.spi.ManagementAware</code> and return the managed object Camel should use.</p><p>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 annota tions you can use to export management on an existing bean. That means that you often use that and just return <code>this</code> in the <code>getManagedObject</code> from the <code>ManagementAware</code> interface. For an example see the code example above with the <code>CustomEndpoint</code>.</p><p>Now in <strong>Camel 2.1</strong> you can do this for all the objects that Camel registers for management which are quite a bunch, but not all.</p><p>For services which do not implement this <code>ManagementAware</code> interface then Camel will fallback to using default wrappers as defined in the table below:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>MBean wrapper</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>CamelContext</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedCamelContext</p></td></tr><tr><td c olspan="1" rowspan="1" class="confluenceTd"><p>Component</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedComponent</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Endpoint</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedEndpoint</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Consumer</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedConsumer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Producer</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedProducer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Route</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedRoute</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Processor</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedProcessor</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Tracer</p></td><td colspan=" 1" rowspan="1" class="confluenceTd"><p>ManagedTracer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Service</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedService</p></td></tr></tbody></table></div><p>In addition to that there are some extended wrappers for specialized types such as</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>MBean wrapper</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>ScheduledPollConsumer</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedScheduledPollConsumer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>BrowsableEndpoint</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedBrowseableEndpoint</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Throttler</p></td><td colspan="1" rowspan="1" cla ss="confluenceTd"><p>ManagedThrottler</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Delayer</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedDelayer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>SendProcessor</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedSendProcessor</p></td></tr></tbody></table></div><p>And in the future we will add additional wrappers for more EIP patterns.</p><h4 id="CamelJMX-ManagementNamingStrategy">ManagementNamingStrategy</h4><p><strong>Available as of Camel 2.1</strong></p><p>Camel provides a pluggable API for naming strategy by <code>org.apache.camel.spi.ManagementNamingStrategy</code>. A default implementation is used to compute the MBean names that all MBeans are registered with.</p><h4 id="CamelJMX-Managementnamingpattern">Management naming pattern</h4><p><strong>Available as of Camel 2.10</strong></p><p>From <strong>Camel 2.10</strong> onwards we made it easier to conf igure a naming pattern for the MBeans. The pattern is used as part of the <code>ObjectName</code> as they key after the domain name.</p><p>By default Camel will use MBean names for the <code>ManagedCamelContextMBean</code> as follows:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div>Notice from <strong>Camel 2.9</strong> onwards its encouraged to use the <code>@ManagedResource</code>, <code>@ManagedAttribute</code>, and <code>@ManagedOperation</code> from the <code>org.apache.camel.api.management</code> package. This allows your custom code to not depend on Spring JARs.<h4 id="CamelJMX-ProgrammingyourownManagedServices">Programming your own Managed Services</h4><p><strong>Available as of Camel 2.1</strong></p><p>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 <code>org.apache.camel.spi.ManagementAware</code> and return the managed object Camel should use.</p><p>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 y ou can use to export management on an existing bean. That means that you often use that and just return <code>this</code> in the <code>getManagedObject</code> from the <code>ManagementAware</code> interface. For an example see the code example above with the <code>CustomEndpoint</code>.</p><p>Now in <strong>Camel 2.1</strong> you can do this for all the objects that Camel registers for management which are quite a bunch, but not all.</p><p>For services which do not implement this <code>ManagementAware</code> interface then Camel will fallback to using default wrappers as defined in the table below:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>MBean wrapper</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>CamelContext</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedCamelContext</p></td></tr><tr><td colspan= "1" rowspan="1" class="confluenceTd"><p>Component</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedComponent</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Endpoint</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedEndpoint</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Consumer</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedConsumer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Producer</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedProducer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Route</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedRoute</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Processor</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedProcessor</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Tracer</p></td><td colspan="1" rows pan="1" class="confluenceTd"><p>ManagedTracer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Service</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedService</p></td></tr></tbody></table></div><p>In addition to that there are some extended wrappers for specialized types such as</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>MBean wrapper</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>ScheduledPollConsumer</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedScheduledPollConsumer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>BrowsableEndpoint</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedBrowseableEndpoint</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Throttler</p></td><td colspan="1" rowspan="1" class="con fluenceTd"><p>ManagedThrottler</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Delayer</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedDelayer</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>SendProcessor</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>ManagedSendProcessor</p></td></tr></tbody></table></div><p>And in the future we will add additional wrappers for more EIP patterns.</p><h4 id="CamelJMX-ManagementNamingStrategy">ManagementNamingStrategy</h4><p><strong>Available as of Camel 2.1</strong></p><p>Camel provides a pluggable API for naming strategy by <code>org.apache.camel.spi.ManagementNamingStrategy</code>. A default implementation is used to compute the MBean names that all MBeans are registered with.</p><h4 id="CamelJMX-Managementnamingpattern">Management naming pattern</h4><p><strong>Available as of Camel 2.10</strong></p><p>From <strong>Camel 2.10</strong> onwards we made it easier to configure a naming pattern for the MBeans. The pattern is used as part of the <code>ObjectName</code> as they key after the domain name.</p><p>By default Camel will use MBean names for the <code>ManagedCamelContextMBean</code> as follows:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[org.apache.camel:context=localhost/camel-1,type=context,name=camel-1 ]]></script> </div></div><p>And from <strong>Camel 2.13</strong> onwards the hostname is not included in the MBean names, so the above example would be as follows:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> @@ -304,7 +304,7 @@ public class CustomEndpoint extends Mock </div></div><p>You may want to do this in OSGi environments in case you do not want the OSGi bundle id as part of the MBean names. As the OSGi bundle id can change if you restart the server, or uninstall and install the same application. You can then do as follows to not use the OSGi bundle id as part of the name:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <script class="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<camelContext id="myCamel" managementNamePattern="#name#"> ]]></script> -</div></div><p>Note this requires that <code>myCamel</code> is unique in the entire JVM. If you install a 2nd Camel application that has the same <code>CamelContext</code> id and <code>managementNamePattern</code> then Camel will fail upon starting, and report a MBean already exists exception.</p><h4 id="CamelJMX-ManagementStrategy">ManagementStrategy</h4><p><strong>Available as of Camel 2.1</strong></p><p>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 <code>MBeanServer</code>, but also event notification is provided as well using the <code>org.apache.camel.spi.EventNotifier</code> API. What it does, for example, is make it easier to provide an adapter for other management products. In addition, it also allows you to provide more details and features that are provided out of the box at Apache.</p><h4 id="C amelJMX-Configuringlevelofgranularityforperformancestatistics">Configuring level of granularity for performance statistics</h4><p><strong>Available as of Camel 2.1</strong></p><p>You can now set a pre set level whether performance statistics is enabled or not when Camel start ups. The levels are</p><ul class="alternate"><li><code>All</code> <strong>default</strong> - Camel will enable statistics for both routes and processors (fine grained)</li><li><code>RoutesOnly</code> - Camel will only enable statistics for routes (coarse grained)</li><li><code>Off</code> - Camel will not enable statistics for any.</li></ul><p>From <strong>Camel 2.9</strong> onwards the performance statistics also include average 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. <strong>Camel 2.11</strong> onwards allows you to explicit disable load pe rformance statistics by setting <code>loadStatisticsEnabled=false</code> on the <jmxAgent>. Note that it will be off if the statics level is configured to off as well. From <strong>Camel 2.13</strong> onwards the load performance statistics is by default disabled. You can enable this by setting <code>loadStatisticsEnabled=true</code> on the <jmxAgent>.</p><p>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.</p><div class="confluence-information-macro confluence-information-macro-information"><p class="title">What does statistics enabled mean?</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>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 exchange s completed/failed, last/total/mina/max/mean processing time, first/last failed time, etc.</p></div></div><p>Using Java DSL you set this level by:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>Note this requires that <code>myCamel</code> is unique in the entire JVM. If you install a 2nd Camel application that has the same <code>CamelContext</code> id and <code>managementNamePattern</code> then Camel will fail upon starting, and report a MBean already exists exception.</p><h4 id="CamelJMX-ManagementStrategy">ManagementStrategy</h4><p><strong>Available as of Camel 2.1</strong></p><p>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 <code>MBeanServer</code>, but also event notification is provided as well using the <code>org.apache.camel.spi.EventNotifier</code> API. What it does, for example, is make it easier to provide an adapter for other management products. In addition, it also allows you to provide more details and features that are provided out of the box at Apache.</p><h4 id="C amelJMX-Configuringlevelofgranularityforperformancestatistics">Configuring level of granularity for performance statistics</h4><p><strong>Available as of Camel 2.1</strong></p><p>You can now set a pre set level whether performance statistics is enabled or not when Camel start ups. The levels are</p><ul class="alternate"><li><p><span><code>Extended</code> - As default but with additional statistics gathered during runtime such as fine grained level of usage of endpoints and more. This options requires Camel 2.16 *</span></p></li><li><span style="font-family: monospace;">All / Default</span> - Camel will enable statistics for both routes and processors (fine grained). From <strong>Camel 2.16</strong> onwards the All option was renamed to Default.</li><li><code>RoutesOnly</code> - Camel will only enable statistics for routes (coarse grained)</li><li><code>Off</code> - Camel will not enable statistics for any.</li></ul><p>From <strong>Camel 2.9</strong> onwards the p erformance statistics also include average 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. <strong>Camel 2.11</strong> onwards allows you to explicit disable load performance statistics by setting <code>loadStatisticsEnabled=false</code> on the <jmxAgent>. Note that it will be off if the statics level is configured to off as well. From <strong>Camel 2.13</strong> onwards the load performance statistics is by default disabled. You can enable this by setting <code>loadStatisticsEnabled=true</code> on the <jmxAgent>.</p><p>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.</p><div class="confluence-information-macro confluence-information-macro-information"><p class="title">What does statistics enabl ed mean?</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>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.</p></div></div><p>Using Java DSL you set this level by:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ // only enable routes when Camel starts context.getManagementStrategy().setStatisticsLevel(ManagementStatisticsLevel.RoutesOnly); ]]></script>
