Chapter 220. Micrometer Component

The micrometer: component allows to collect various metrics directly from Camel routes. Supported metric types are counter, summary, and timer. Micrometer provides simple way to measure the behaviour of an application. Configurable reporting backends (via Micrometer registries) enable different integration options for collecting and visualizing statistics.

The component also provides a MicrometerRoutePolicyFactory which allows to expose route statistics using Micrometer as well as EventNotifier implementations for counting routes and timing exchanges from their creation to their completion.

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

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

micrometer:[ counter | summary | timer ]:metricname[?options]

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

The Micrometer endpoint is configured using URI syntax:

micrometer:metricsType:metricsName

with the following path and query parameters:

The component supports 3 options, which are listed below.

By default the Camel Micrometer component creates a SimpleMeterRegistry instance, suitable mainly for testing. You should define a dedicated registry by providing a MeterRegistry bean. Micrometer registries primarily determine the backend monitoring system to be used. A CompositeMeterRegistry can be used to address more than one monitoring target.

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 = MicrometerComponent.METRICS_REGISTRY_NAME)
    public MeterRegistry getMeterRegistry() {
        CompositeMeterRegistry registry = ...;
        registry.add(...);
        // ...
        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(MicrometerComponent.METRIC_REGISTRY_NAME)
    MetricRegistry registry() {
        CompositeMeterRegistry registry = ...;
        registry.add(...);
        // ...
        return registry;
    }
}

Each meter has type and name. Supported types are counter, distribution summary and timer. If no type is provided then a counter is used by default.

The meter name is a string that is evaluated as Simple expression. In addition to using the CamelMetricsName header (see below), this allows to select the meter depending on exchange data.

The optional tags URI parameter is a comma-separated string, consisting of key=value expressions. Both key and value are strings that are also evaluated as Simple expression. E.g. the URI parameter tags=X=${header.Y} would assign the current value of header Y to the key X.

from("direct:in")
    .setHeader(MicrometerConstants.HEADER_METRIC_NAME, constant("new.name"))
    .setHeader(MicrometerConstants.HEADER_METRIC_TAGS, constant(Tags.of("dynamic-key", "dynamic-value")))
    .to("metrics:counter:name.not.used?tags=key=value")
    .to("direct:out");

micrometer:counter:name[?options]

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

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

// decrement counter simple.counter by 3
from("direct:in")
    .to("micrometer:counter:simple.counter?decrement=${header.X}")
    .to("direct:out");

// update counter simple.counter by 417
from("direct:in")
    .setHeader(MicrometerConstants.HEADER_COUNTER_INCREMENT, constant(417.0D))
    .to("micrometer:counter:simple.counter?increment=7")
    .to("direct:out");

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

micrometer:summary:metricname[?options]

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

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

from("direct:in")
    .to("micrometer:summary:simple.histogram?value=${header.X}")
    .to("direct:out");

// adds value 992.0 to simple.histogram
from("direct:in")
    .setHeader(MicrometerConstants.HEADER_HISTOGRAM_VALUE, constant(992.0D))
    .to("micrometer:summary:simple.histogram?value=700")
    .to("direct:out")

micrometer:timer:metricname[?options]

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

// sets timer action using header
from("direct:in")
    .setHeader(MicrometerConstants.HEADER_TIMER_ACTION, MicrometerTimerAction.start)
    .to("micrometer:timer:simple.timer")
    .to("direct:out");

This factory allows to add a RoutePolicy for each route in order to exposes route utilization statistics using Micrometer. 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 MicrometerRoutePolicyFactory());

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

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

The MicrometerRoutePolicyFactory and MicrometerRoutePolicy supports the following options:

If JMX is enabled in the CamelContext, the MBean is registered in the type=services tree with name=MicrometerRoutePolicy.

This factory allows to use metrics to capture Message History performance statistics while routing messages. It works by using a Micrometer 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 MicrometerMessageHistoryFactory());

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

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

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 get the service from the CamelContext as shown:

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

If JMX is enabled in the CamelContext, the MBean is registered in the type=services tree with name=MicrometerMessageHistory.

There is a MicrometerRouteEventNotifier (counting added and running routes) and a MicrometerExchangeEventNotifier (timing exchanges from their creation to their completion).

EventNotifiers can be added to the CamelContext, e.g.:

camelContext.getManagementStrategy().addEventNotifier(new MicrometerExchangeEventNotifier())

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:

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

If JMX is enabled in the CamelContext, the MBean is registered in the type=services tree with name=MicrometerEventNotifier.

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.

Micrometer uses MeterRegistry implementations in order to publish statistics. While in production scenarios it is advisable to select a dedicated backend like Prometheus or Graphite, it may be sufficient for test or local deployments to publish statistics to JMX.

In order to achieve this, add the following dependency:

    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-registry-jmx</artifactId>
      <version>${micrometer-version}</version>
    </dependency>

and add a JmxMeterRegistry instance:

    @Bean(name = MicrometerComponent.METRICS_REGISTRY_NAME)
    public MeterRegistry getMeterRegistry() {
        CompositeMeterRegistry meterRegistry = new CompositeMeterRegistry();
        meterRegistry.add(...);
        meterRegistry.add(new JmxMeterRegistry(
           CamelJmxConfig.DEFAULT,
           Clock.SYSTEM,
           HierarchicalNameMapper.DEFAULT));
        return meterRegistry;
    }
}

The HierarchicalNameMapper strategy determines how meter name and tags are assembled into an MBean name.

camel-example-micrometer provides an example how to set up Micrometer monitoring with Camel using Java configuration and a Prometheus backend.