Micrometer

Since Camel 2.22

Only producer is supported

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>

URI format

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

Options

Configuring Options

Camel components are configured on two separate levels:

  • component level

  • endpoint level

Configuring Component Options

The component level is the highest level which holds general and common configurations that are inherited by the endpoints. For example a component may have security settings, credentials for authentication, urls for network connection and so forth.

Some components only have a few options, and others may have many. Because components typically have pre configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.

Configuring components can be done with the Component DSL, in a configuration file (application.properties|yaml), or directly with Java code.

Configuring Endpoint Options

Where you find yourself configuring the most is on endpoints, as endpoints often have many options, which allows you to configure what you need the endpoint to do. The options are also categorized into whether the endpoint is used as consumer (from) or as a producer (to), or used for both.

Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL and DataFormat DSL as a type safe way of configuring endpoints and data formats in Java.

A good practice when configuring options is to use Property Placeholders, which allows to not hardcode urls, port numbers, sensitive information, and other settings. In other words placeholders allows to externalize the configuration from your code, and gives more flexibility and reuse.

The following two sections lists all the options, firstly for the component followed by the endpoint.

Component Options

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

Name Description Default Type

lazyStartProducer (producer)

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

boolean

autowiredEnabled (advanced)

Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc.

true

boolean

metricsRegistry (advanced)

To use a custom configured MetricRegistry.

MeterRegistry

Endpoint Options

The Micrometer endpoint is configured using URI syntax:

micrometer:metricsType:metricsName

with the following path and query parameters:

Path Parameters (3 parameters)

Name Description Default Type

metricsType (producer)

Required Type of metrics.

Enum values:

  • counter

  • summary

  • timer

Type

metricsName (producer)

Required Name of metrics.

String

tags (producer)

Tags of metrics.

Iterable

Query Parameters (6 parameters)

Name Description Default Type

action (producer)

Action expression when using timer type.

Enum values:

  • start

  • stop

String

decrement (producer)

Decrement value expression when using counter type.

String

increment (producer)

Increment value expression when using counter type.

String

metricsDescription (producer)

Description of metrics.

String

value (producer)

Value expression when using histogram type.

String

lazyStartProducer (producer (advanced))

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

boolean

Message Headers

The Micrometer component supports 7 message header(s), which is/are listed below:

Name Description Default Type

CamelMetricsTimerAction (producer)

Constant: HEADER_TIMER_ACTION

Override timer action in URI.

Enum values:

  • start

  • stop

MicrometerTimerAction

CamelMetricsHistogramValue (producer)

Constant: HEADER_HISTOGRAM_VALUE

Override histogram value in URI.

long

CamelMetricsCounterDecrement (producer)

Constant: HEADER_COUNTER_DECREMENT

Override decrement value in URI.

Double

CamelMetricsCounterIncrement (producer)

Constant: HEADER_COUNTER_INCREMENT

Override increment value in URI.

Double

CamelMetricsName (producer)

Constant: HEADER_METRIC_NAME

Override name value in URI.

String

CamelMetricsDescription (producer)

Constant: HEADER_METRIC_DESCRIPTION

Override description value in URI.

String

CamelMetricsTags (producer)

Constant: HEADER_METRIC_TAGS

To augment meter tags defined as URI parameters.

Iterable

Meter Registry

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.

Default Camel Metrics

Some Camel specific metrics are available out of the box.

Name Type Description

camel.message.history

timer

Sample of performance of each node in the route when message history is enabled

camel.routes.added

gauge

Number of routes in total

camel.routes.reloaded

gauge

Number of routes that has been reloaded

camel.routes.running

gauge

Number of routes currently running

camel.exchanges.inflight

gauge

Route inflight messages

camel.exchanges.total

counter

Total number of processed exchanges

camel.exchanges.succeeded

counter

Number of successfully completed exchange

camel.exchanges.failed

counter

Number of failed exchanges

camel.exchanges.failures.handled

counter

Number of failures handled

camel.exchanges.external.redeliveries

counter

Number of external initiated redeliveries (such as from JMS broker)

camel.exchange.event.notifier

gauge + summary

Metrics for message created, sent, completed, and failed events

camel.route.policy

gauge + summary

Route performance metrics

camel.route.policy.long.task

gauge + summary

Route long task metric

Using legacy metrics naming

In Camel 3.20 or older, then the naming of metrics are using camelCase style. However, since Camel 3.21 onwards, the naming is using micrometer convention style (see table above).

To use the legacy naming, then you can use the LEGACY naming from the xxxNamingStrategy interfaces.

For example:

MicrometerRoutePolicyFactory factory = new MicrometerRoutePolicyFactory();
factory.setNamingStrategy(MicrometerRoutePolicyNamingStrategy.LEGACY);

The naming style can be configured on:

  • MicrometerRoutePolicyFactory

  • MicrometerExchangeEventNotifier

  • MicrometerRouteEventNotifier

  • MicrometerMessageHistoryFactory

Usage of producers

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.

Headers

The meter name defined in URI can be overridden by populating a header with name CamelMetricsName. The meter tags defined as URI parameters can be augmented by populating a header with name CamelMetricsTags.

For example

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

will update a counter with name new.name instead of name.not.used using the tag dynamic-key with value dynamic-value in addition to the tag key with value value.

All Metrics specific headers are removed from the message once the Micrometer endpoint finishes processing of exchange. While processing exchange Micrometer endpoint will catch all exceptions and write log entry using level warn.

Counter

micrometer:counter:name[?options]

Options

Name Default Description

increment

-

Double value to add to the counter

decrement

-

Double value to subtract from the counter

If neither increment or decrement is defined then counter value will be incremented by one. If increment and decrement are both defined only increment operation is called.

// 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");

Both increment and decrement values are evaluated as Simple expressions with a Double result, e.g. if header X contains a value that evaluates to 3.0, the simple.counter counter is decremented by 3.0:

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

Headers

Like in camel-metrics, specific Message headers can be used to override increment and decrement values specified in the Micrometer endpoint URI.

Name Description Expected type

CamelMetricsCounterIncrement

Override increment value in URI

Double

CamelMetricsCounterDecrement

Override decrement value in URI

Double

 
// 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");

Distribution Summary

micrometer:summary:metricname[?options]

Options

Name Default Description

value

-

Value to use in histogram

If no value is not set, nothing is added to histogram and warning is logged.

// 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");

value is evaluated as Simple expressions with a Double result, e.g. if header X contains a value that evaluates to 3.0, this value is registered with the simple.histogram:

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

Headers

Like in camel-metrics, a specific Message header can be used to override the value specified in the Micrometer endpoint URI.

Name Description Expected type

CamelMetricsHistogramValue

Override histogram value in URI

Long

 
// 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")

Timer

micrometer:timer:metricname[?options]

Options

Name Default Description

action

-

start or stop

If no action or invalid value is provided then warning is logged without any timer update. If action start is called on an already running timer or stop is called on an unknown timer, nothing is updated and warning is logged.

// 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");

Timer.Sample objects are stored as Exchange properties between different Metrics component calls.

action is evaluated as a Simple expression returning a result of type MicrometerTimerAction.

Headers

Like in camel-metrics, a specific Message header can be used to override action value specified in the Micrometer endpoint URI.

Name Description Expected type

CamelMetricsTimerAction

Override timer action in URI

org.apache.camel.component.micrometer.MicrometerTimerAction

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

Using Micrometer route policy factory

MicrometerRoutePolicyFactory 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.

Instead of using the MicrometerRoutePolicyFactory you can define a dedicated MicrometerRoutePolicy per route you want to instrument, in case you only want to instrument a few selected routes.

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:

Name Default Description

prettyPrint

false

Whether to use pretty print when outputting statistics in json format

meterRegistry

Allow to use a shared MeterRegistry. If none is provided then Camel will create a shared instance used by the this CamelContext.

durationUnit

TimeUnit.MILLISECONDS

The unit to use for duration in when dumping the statistics as json.

configuration

see below

MicrometerRoutePolicyConfiguration.class

The MicrometerRoutePolicyConfiguration supports the following options:

Name Default Description

additionalCounters

true

activates all additional counters

exchangesSucceeded

true

activates counter for succeeded exchanges

exchangesFailed

true

activates counter for failed exchanges

exchangesTotal

true

activates counter for total count of exchanges

externalRedeliveries

true

activates counter for redeliveries of exchanges

failuresHandled

true

activates counter for handled failures

longTask

false

activates long task timer (current processing time for micrometer)

timerInitiator

null

Consumer<Timer.Builder> for custom initialize Timer

longTaskInitiator

null

Consumer<LongTaskTimer.Builder> for custom initialize LongTaskTimer

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

Using Micrometer message history factory

MicrometerMessageHistoryFactory 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:

Name Default Description

prettyPrint

false

Whether to use pretty print when outputting statistics in json format

meterRegistry

Allow to use a shared MeterRegistry. If none is provided then Camel will create a shared instance used by the this CamelContext.

durationUnit

TimeUnit.MILLISECONDS

The unit to use for duration when dumping the statistics as json.

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.

Micrometer event notification

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.

Instrumenting Camel thread pools

InstrumentedThreadPoolFactory 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 Threading Model.

Exposing Micrometer statistics in JMX

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:

  • Java

  • CDI

    @Bean(name = MicrometerConstants.METRICS_REGISTRY_NAME)
    public MeterRegistry getMeterRegistry() {
        CompositeMeterRegistry meterRegistry = new CompositeMeterRegistry();
        meterRegistry.add(...);
        meterRegistry.add(new JmxMeterRegistry(
           CamelJmxConfig.DEFAULT,
           Clock.SYSTEM,
           HierarchicalNameMapper.DEFAULT));
        return meterRegistry;
    }
    @Produces
    @Named(MicrometerConstants.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.

Using Camel Micrometer with Camel Main

When you use Camel standalone (camel-main), then if you need to expose metrics for Prometheus, then you can use camel-micrometer-prometheus JAR. And easily enable and configure this from application.properties as shown:

# enable HTTP server with metrics
camel.server.enabled=true
camel.server.metricsEnabled=true

# turn on micrometer metrics
camel.metrics.enabled=true
# include more camel details
camel.metrics.enableMessageHistory=true
# include additional out-of-the-box micrometer metrics for cpu, jvm and used file descriptors
camel.metrics.binders=processor,jvm-info,file-descriptor

Using Camel Micrometer with Spring Boot

When you use camel-micrometer-starter with Spring Boot, then Spring Boot auto configuration will automatically enable metrics capture if a io.micrometer.core.instrument.MeterRegistry is available.

For example to capture data with Prometheus, you can add the following dependency:

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

See the following table for options to specify what metrics to capture, or to turn it off.