Chapter 219. Metrics Component

The metrics: component allows to collect various metrics directly from Camel routes. Supported metric types are counter, histogram, meter, timer and gauge. Metrics provides simple way to measure behaviour of application. Configurable reporting backend is enabling different integration options for collecting and visualizing statistics. The component also provides a MetricsRoutePolicyFactory which allows to expose route statistics using Dropwizard Metrics, see bottom of page for details.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-metrics</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

metrics:[ meter | counter | histogram | timer | gauge ]:metricname[?options]

The Metrics component supports 2 options, which are listed below.

The Metrics endpoint is configured using URI syntax:

metrics:metricsType:metricsName

with the following path and query parameters:

The component supports 3 options, which are listed below.

Camel Metrics component uses by default a MetricRegistry instance with a Slf4jReporter that has a 60 second reporting interval. This default registry can be replaced with a custom one by providing a MetricRegistry bean. If multiple MetricRegistry beans exist in the application, the one with name metricRegistry is used.

For example using Spring Java Configuration:

@Configuration
public static class MyConfig extends SingleRouteCamelConfiguration {

    @Bean
    @Override
    public RouteBuilder route() {
        return new RouteBuilder() {
            @Override
            public void configure() throws Exception {
                // define Camel routes here
            }
        };
    }

    @Bean(name = MetricsComponent.METRIC_REGISTRY_NAME)
    public MetricRegistry getMetricRegistry() {
        MetricRegistry registry = ...;
        return registry;
    }
}

Or using CDI:

class MyBean extends RouteBuilder {

    @Override
    public void configure() {
      from("...")
          // Register the 'my-meter' meter in the MetricRegistry below
          .to("metrics:meter:my-meter");
    }

    @Produces
    // If multiple MetricRegistry beans
    // @Named(MetricsComponent.METRIC_REGISTRY_NAME)
    MetricRegistry registry() {
        MetricRegistry registry = new MetricRegistry();
        // ...
        return registry;
    }
}

Each metric has type and name. Supported types are counter, histogram, meter, timer and gauge. Metric name is simple string. If metric type is not provided then type meter is used by default.

from("direct:in")
    .setHeader(MetricsConstants.HEADER_METRIC_NAME, constant("new.name"))
    .to("metrics:counter:name.not.used")
    .to("direct:out");

metrics:counter:metricname[?options]

// update counter simple.counter by 7
from("direct:in")
    .to("metric:counter:simple.counter?increment=7")
    .to("direct:out");

// increment counter simple.counter by 1
from("direct:in")
    .to("metric:counter:simple.counter")
    .to("direct:out");

// decrement counter simple.counter by 3
from("direct:in")
    .to("metrics:counter:simple.counter?decrement=3")
    .to("direct:out");

// update counter simple.counter by 417
from("direct:in")
    .setHeader(MetricsConstants.HEADER_COUNTER_INCREMENT, constant(417L))
    .to("metrics:counter:simple.counter?increment=7")
    .to("direct:out");

// updates counter using simple language to evaluate body.length
from("direct:in")
    .setHeader(MetricsConstants.HEADER_COUNTER_INCREMENT, simple("${body.length}"))
    .to("metrics:counter:body.length")
    .to("mock:out");

metrics:histogram:metricname[?options]

// adds value 9923 to simple.histogram
from("direct:in")
    .to("metric:histogram:simple.histogram?value=9923")
    .to("direct:out");

// nothing is added to simple.histogram; warning is logged
from("direct:in")
    .to("metric:histogram:simple.histogram")
    .to("direct:out");

// adds value 992 to simple.histogram
from("direct:in")
    .setHeader(MetricsConstants.HEADER_HISTOGRAM_VALUE, constant(992L))
    .to("metrics:histogram:simple.histogram?value=700")
    .to("direct:out")

metrics:meter:metricname[?options]

// marks simple.meter without value
from("direct:in")
    .to("metric:simple.meter")
    .to("direct:out");

// marks simple.meter with value 81
from("direct:in")
    .to("metric:meter:simple.meter?mark=81")
    .to("direct:out");

// updates meter simple.meter with value 345
from("direct:in")
    .setHeader(MetricsConstants.HEADER_METER_MARK, constant(345L))
    .to("metrics:meter:simple.meter?mark=123")
    .to("direct:out");

metrics:timer:metricname[?options]

// measure time taken by route "calculate"
from("direct:in")
    .to("metrics:timer:simple.timer?action=start")
    .to("direct:calculate")
    .to("metrics:timer:simple.timer?action=stop");

// sets timer action using header
from("direct:in")
    .setHeader(MetricsConstants.HEADER_TIMER_ACTION, TimerAction.start)
    .to("metrics:timer:simple.timer")
    .to("direct:out");

metrics:gauge:metricname[?options]

// update gauge "simple.gauge" by a bean "mySubjectBean"
from("direct:in")
    .to("metrics:gauge:simple.gauge?subject=#mySubjectBean")
    .to("direct:out");

// update gauge simple.gauge by a String literal "myUpdatedSubject"
from("direct:in")
    .setHeader(MetricsConstants.HEADER_GAUGE_SUBJECT, constant("myUpdatedSubject"))
    .to("metrics:counter:simple.gauge?subject=#mySubjectBean")
    .to("direct:out");

This factory allows to add a RoutePolicy for each route which exposes route utilization statistics using Dropwizard metrics. This factory can be used in Java and XML as the examples below demonstrates. 

From Java you just add the factory to the CamelContext as shown below:

context.addRoutePolicyFactory(new MetricsRoutePolicyFactory());

And from XML DSL you define a <bean> as follows:

  <!-- use camel-metrics route policy to gather metrics for all routes -->
  <bean id="metricsRoutePolicyFactory" class="org.apache.camel.component.metrics.routepolicy.MetricsRoutePolicyFactory"/>

The MetricsRoutePolicyFactory and MetricsRoutePolicy supports the following options:

From Java code you can get hold of the com.codahale.metrics.MetricRegistry from the org.apache.camel.component.metrics.routepolicy.MetricsRegistryService as shown below:

MetricRegistryService registryService = context.hasService(MetricsRegistryService.class);
if (registryService != null) {
  MetricsRegistry registry = registryService.getMetricsRegistry();
  ...
}

Available as of Camel 2.17

This factory allows to use metrics to capture Message History performance statistics while routing messages. It works by using a metrics Timer for each node in all the routes. This factory can be used in Java and XML as the examples below demonstrates. 

From Java you just set the factory to the CamelContext as shown below:

context.setMessageHistoryFactory(new MetricsMessageHistoryFactory());

And from XML DSL you define a <bean> as follows:

  <!-- use camel-metrics message history to gather metrics for all messages being routed -->
  <bean id="metricsMessageHistoryFactory" class="org.apache.camel.component.metrics.messagehistory.MetricsMessageHistoryFactory"/>

The following options is supported on the factory:

At runtime the metrics can be accessed from Java API or JMX which allows to gather the data as json output.

From Java code you can do get the service from the CamelContext as shown:

MetricsMessageHistoryService service = context.hasService(MetricsMessageHistoryService.class);
String json = service.dumpStatisticsAsJson();

And the JMX API the MBean is registered in the type=services tree with name=MetricsMessageHistoryService.

Available as of Camel 2.18

This factory allows you to gather performance information about Camel Thread Pools by injecting a InstrumentedThreadPoolFactory which collects information from inside of Camel. See more details at Advanced configuration of CamelContext using Spring