This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Child pages
  • Metrics Component

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Typos and formatting.

...

Available as of Camel 2.14

The metrics: component component allows to collect various metrics directly from Camel routes. Supported metric types are counterhistogram, meter and timerMetrics provides simple way to measure behaviour behavior of application. Configurable reporting backend is enabling different integration options for collecting and visualizing statistics. The

The metrics component also provides a MetricsRoutePolicyFactory which that allows to expose route statistics to be exposed using codehale Codahale metrics, see . See bottom of page for details.

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

Code Block
languagexml
<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>

URI

...

Format

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

...

Camel Metrics Component uses by default MetricRegistry with Slf4jReporter and 60 second reporting interval. Default registry can be replaced with custom one by providing bean with name metricRegistry in Camel registry. 

For example using Spring Java Configuration.:

Code Block
languagejava
@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;
    }
}
Warning

MetricRegistry uses internal thread(s) for reporting. There is no public API in DropWizard version 3.0.1 for users to clean up on exit. Thus using Camel Metrics Component leads to Java classloader leak and my cause OutOfMemoryErrors in some cases.

Usage

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

...

Metric name defined in URI can be overridden by using header with name CamelMetricsName.

For example

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

will update counter with name new.name instead of name.not.used.

All Metrics All metrics specific headers are removed from the message once Metrics endpoint finishes processing of exchange. While processing exchange Metrics endpoint will catch all exceptions and write log entry using the exchange metrics endpoint any exceptions thrown are caught and written to as a log entry at level warn.

Anchor
counter
counter
Metrics

...

Type Counter

Code Block
languagetext
metrics:counter:metricname[?options]

Options

NameDefaultDescription
increment increment-Long value to add to the counter
decrement-Long 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 only increment operation is called. 

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

...

Message headers can be used to override increment and decrement values specified in Metrics the metrics component URI.

NameDescriptionExpected type
CamelMetricsCounterIncrement CamelMetricsCounterIncrementOverride increment value in URILong
CamelMetricsCounterDecrement CamelMetricsCounterDecrementOverride decrement value in URILong
Code Block
languagejava
// update counter simple.counter by 417
from("direct:in")
    .setHeader(MetricsConstants.HEADER_COUNTER_INCREMENT, constant(417L))
    .to("metric:counter:simple.counter?increment=7")
    .to("direct:out");

...

Options

NameDefaultDescription
value-Value to use in histogram

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

...

Message header can be used to override value specified in Metrics metrics component URI.

NameDescriptionExpected type
CamelMetricsHistogramValueOverride histogram value in URILong
Code Block
languagejava
// addsAdds value 992 to simple.histogram
from("direct:in")
    .setHeader(MetricsConstants.HEADER_HISTOGRAM_VALUE, constant(992L))
    .to("metric:histogram:simple.histogram?value=700")
    .to("direct:out")

...

Options

NameDefaultDescription
mark mark-Long value to use as mark

If mark is not set then meter.mark() is called without argument.

...

Message header can be used to override mark value specified in Metrics in metrics component URI.

NameDescriptionExpected type
CamelMetricsMeterMarkOverride mark value in URILong
Code Block
languagejava
// updates meter simple.meter with value 345
from("direct:in")
    .setHeader(MetricsConstants.HEADER_METER_MARK, constant(345L))
    .to("metric:meter:simple.meter?mark=123")
    .to("direct:out");

...

Options

NameDefaultDescription
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 already running timer or stop is called on not running timer then nothing is updated and warning is logged.

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

TimerContext objects are stored as as Exchange properties between different Metrics different metrics component calls.

Headers

Message header can be used to override action value specified in Metrics in metrics component URI.

NameDescriptionExpected type
CamelMetricsTimerActionOverride timer action in URIorg.apache.camel.component.metrics.timer.TimerEndpoint.TimerAction
Code Block
languagejava
// sets timer action using header
from("direct:in")
    .setHeader(MetricsConstants.HEADER_TIMER_ACTION, TimerAction.start)
    .to("metric:timer:simple.timer")
    .to("direct:out");

MetricsRoutePolicyFactory

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

Tip

Instead of using the the MetricsRoutePolicyFactory you can define a MetricsRoutePolicy 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:

Code Block
context.addRoutePolicyFactory(new MetricsRoutePolicyFactory());

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

Code Block
  <!-- 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:

NameDefaultDescription
useJmxfalseWhether to report fine grained statistics to JMX by using the com.codahale.metrics.JmxReporter.
Notice that if JMX is enabled on CamelContext then a MetricsRegistryService mbean is enlisted under the services type in the JMX tree. That mbean MBean has a single operation to output the statistics using jsonJSON. Setting useJmx to true is only needed if you want fine grained mbeans MBeans per statistics type.
jmxDomainorg.apache.camel.metricsThe JMX domain name.
prettyPrintfalseWhether to use pretty print when outputting statistics in json JSON format.
metricsRegistry Allow to use a shared com.codahale.metrics.MetricRegistry. If none one is provided then not configured Camel will create a shared instance used for use by the this CamelContext.
rateUnitTimeUnit.SECONDSThe unit to use for rate in the metrics reporter or when dumping the statistics as jsonJSON.
durationUnitTimeUnit.MILLISECONDSThe unit to use for duration in the metrics reporter or when dumping the statistics as jsonJSON.
namePattern##name##.##routeId##.##type##

Camel 2.17: The name pattern to use. Uses dot as separators, but you can change that. The

values

values ##name##, ##routeId##,

and

and ##type## will be replaced with actual value.

Where

Where ###name### is the name of

the

the CamelContext. ###routeId### is the

name

id of the route

. And

, where ###type### is the value of responses.

 

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

Code Block
MetricRegistryService registryService = context.hasService(MetricsRegistryService.class);

if (registryService != null) {
  MetricsRegistry registry = registryService.getMetricsRegistry();
  // ...
}

MetricsMessageHistoryFactory

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 In Java you just set the factory to on the CamelContext as shown below:

Code Block
context.setMessageHistoryFactory(new MetricsMessageHistoryFactory());

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

Code Block
  <!-- 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:

NameDefaultDescription
useJmxfalseWhether to report fine grained statistics to JMX by using the com.codahale.metrics.JmxReporter.
Notice that if JMX is enabled on CamelContext then a MetricsRegistryService mbean MBean is enlisted under the services type in the JMX tree. That mbean MBean has a single operation to output the statistics using jsonJSON. Setting useJmx to true is only needed if you want fine grained mbeans MBeans per statistics type.
jmxDomainorg.apache.camel.metricsThe JMX domain name.
prettyPrintfalseWhether to use pretty print when outputting statistics in json JSON format.
metricsRegistry Allow to use a shared com.codahale.metrics.MetricRegistry. If none one is not provided then Camel will create a shared instance used for use by the this CamelContext.
rateUnitTimeUnit.SECONDSThe unit to use for rate in the metrics reporter or when dumping the statistics as jsonJSON.
durationUnitTimeUnit.MILLISECONDSThe unit to use for duration in the metrics reporter or when dumping the statistics as json.JSON
namePattern

##name##.##routeId##.###id###.##type##

The name pattern to use. Uses dot as separators, but you can change that. The values ##name##, ##routeId##, ##type##, and and ###id### will be replaced with actual value. Where Where ###name### is the name of the the CamelContext.###routeId### is the name of the route. The The ###id### pattern represents the node id. And , where ###type### is the value of history.

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

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

Code Block
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