Since Camel 2.22
Only producer is supported
The Micrometer component allows collecting various metrics directly from Camel routes. Supported metric types are counter, summary, and timer. Micrometer provides a simple way to measure the behaviour of an application. The configurable reporting backend (via Micrometer registries) enables 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>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.
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 exchanges |
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 messages 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 |
In Camel 3.20 or older, then the naming of metrics is using camelCase style. However, since Camel 3.21 onwards, the naming is using the 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
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 selecting 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.
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.
micrometer:counter:name[?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 value of the counter 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");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");micrometer:summary:metricname[?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");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")micrometer:timer:metricname[?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.
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 |
|
// sets timer action using header
from("direct:in")
.setHeader(MicrometerConstants.HEADER_TIMER_ACTION, MicrometerTimerAction.start)
.to("micrometer:timer:simple.timer")
.to("direct:out");MicrometerRoutePolicyFactory allows to add a RoutePolicy for each
route to expose route utilization statistics using Micrometer.
This factory can be used in Java and XML as the examples below
demonstrates.
|
Note
|
Instead of using the |
From Java, you 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 using a shared |
|
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 |
|---|---|---|
contextEnabled |
true |
whether to include counter for context level metrics |
routeEnabled |
true |
whether to include counter for route level metrics |
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.
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 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 are supported on the factory:
| Name | Default | Description |
|---|---|---|
prettyPrint |
false |
Whether to use pretty print when outputting statistics in json format |
meterRegistry |
Allow using a shared |
|
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.
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 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.
InstrumentedThreadPoolFactory allows you to gather performance information about Camel Thread Pools by injecting a InstrumentedThreadPoolFactory
which collects information from the inside of Camel.
See more details at Threading Model.
Micrometer uses MeterRegistry implementations 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.
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
-
@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; }
- CDI
-
@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.
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-descriptorWhen you use camel-micrometer-starter with Spring Boot, then Spring Boot autoconfiguration 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.
spring-boot:partial$starter.adoc