Chapter 104. Metrics

Metrics Component
Copia collegamento

Available as of Camel 2.14

The metrics: component allows to collect various metrics directly from Camel routes. Supported metric types are counter, histogram, meter and timer. 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 codehale 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>

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

Copy to Clipboard

Toggle word wrap

URI format
Copia collegamento

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

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

Copy to Clipboard

Toggle word wrap

Metric Registry
Copia collegamento

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.

@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;
    }
}

@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;
    }
}

Copy to Clipboard

Toggle word wrap

Warning

MetricRegistry uses internal thread(s) for reporting. There is no public API in 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
Copia collegamento

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

Headers
Copia collegamento

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

For example

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

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

Copy to Clipboard

Toggle word wrap

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

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 level warn.

Metrics type counter
Copia collegamento

metrics:counter:metricname[?options]

metrics:counter:metricname[?options]

Copy to Clipboard

Toggle word wrap

Options
Copia collegamento

Expand

Name	Default	Description
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 increment operation is called.

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

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

Headers
Copia collegamento

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

Expand

Name	Description	Expected type
CamelMetricsCounterIncrement	Override increment value in URI	Long
CamelMetricsCounterDecrement	Override decrement value in URI	Long

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

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

Metric type histogram
Copia collegamento

metrics:histogram:metricname[?options]

metrics:histogram:metricname[?options]

Copy to Clipboard

Toggle word wrap

Options
Copia collegamento

Expand

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("metric:histogram:simple.histogram?value=9923")
    .to("direct:out");

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

Headers
Copia collegamento

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

Expand

Name	Description	Expected type
CamelMetricsHistogramValue	Override histogram value in URI	Long

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

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

Copy to Clipboard

Toggle word wrap

Metric type meter
Copia collegamento

metrics:meter:metricname[?options]

metrics:meter:metricname[?options]

Copy to Clipboard

Toggle word wrap

Options
Copia collegamento

Expand

Name	Default	Description
mark	-	Long value to use as mark

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

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

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

Headers
Copia collegamento

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

Expand

Name	Description	Expected type
CamelMetricsMeterMark	Override mark value in URI	Long

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

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

Copy to Clipboard

Toggle word wrap

Metrics type timer
Copia collegamento

metrics:timer:metricname[?options]

metrics:timer:metricname[?options]

Copy to Clipboard

Toggle word wrap

Options
Copia collegamento

Expand

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

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

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

Copy to Clipboard

Toggle word wrap

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

Headers
Copia collegamento

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

Expand

Name	Description	Expected type
CamelMetricsTimerAction	Override timer action in URI	`org.apache.camel.component.metrics.timer.TimerEndpoint.TimerAction`

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

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

Copy to Clipboard

Toggle word wrap

MetricsRoutePolicyFactory
Copia collegamento

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

Tip

Instead of using 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:

context.addRoutePolicyFactory(new MetricsRoutePolicyFactory());

context.addRoutePolicyFactory(new MetricsRoutePolicyFactory());

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

The MetricsRoutePolicyFactory and MetricsRoutePolicy supports the following options:

Expand

Name	Default	Description
`useJmx`	`false`	Whether 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 has a single operation to output the statistics using json. Setting `useJmx` to true is only needed if you want fine grained mbeans per statistics type.
`jmxDomain`	`org.apache.camel.metrics`	The JMX domain name
`prettyPrint`	`false`	Whether to use pretty print when outputting statistics in json format
`metricsRegistry`		Allow to use a shared `com.codahale.metrics.MetricRegistry`. If none is provided then Camel will create a shared instance used by the this CamelContext.
`rateUnit`	`TimeUnit.SECONDS`	The unit to use for rate in the metrics reporter or when dumping the statistics as json.
`durationUnit`	`TimeUnit.MILLISECONDS`	The unit to use for duration in the metrics reporter or when dumping the statistics as json.
`namePattern`	`##name##.##routeId##.##type##`	Camel 2.17: The name pattern to use. Uses dot as separators, but you can change that. The values `##name##`, `##routeId##`, and `##type##` will be replaced with actual value. Where `###name###` is the name of the CamelContext, `###routeId###` is the name of the route, and `###type###` is the value of responses.

From Java code tou 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();
  ...
}

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

Copy to Clipboard

Toggle word wrap

MetricsMessageHistoryFactory
Copia collegamento

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());

context.setMessageHistoryFactory(new MetricsMessageHistoryFactory());

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

The following options are supported on the factory:

Expand

Name	Default	Description
`useJmx`	`false`	Whether to report fine-grained statistics to JMX using the `com.codahale.metrics.JmxReporter`. Note that if JMX is enabled on CamelContext, a `MetricsRegistryService` MBean is enlisted under the services type in the JMX tree. That MBean has a single operation to output the statistics using JSon. Setting `useJmx` to `true` is needed only if you want fine-grained MBeans per statistics type.
`jmxDomain`	`org.apache.camel.metrics`	The JMX domain name.
`prettyPrint`	`false`	Whether to use pretty print when outputting statistics in JSon format
`metricsRegistry`		Enable a shared `com.codahale.metrics.MetricRegistry`. If none is provided, Camel will create a shared instance for this CamelContext.
`rateUnit`	`TimeUnit.SECONDS`	The unit to use for rate in the metrics reporter or when dumping the statistics as JSon.
`durationUnit`	`TimeUnit.MILLISECONDS`	The unit to use for duration in the metrics reporter or when dumping the statistics as 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 `###id###` will be replaced with actual value. Where `###name###` is the name of the CamelContext, `###routeId###` is the name of the route, the `###id###` pattern represents the node ID, and `###type###` is the value of history.

At runtime the metrics can be accessed from Java API or JMX, which enable you to gather the data as JSon output. From Java code you can get the service from the CamelContext as follows:

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

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

Copy to Clipboard

Toggle word wrap

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

Questo contenuto non è disponibile nella lingua selezionata.

Metrics Component
Copia collegamento

URI format
Copia collegamento

Metric Registry
Copia collegamento

Usage
Copia collegamento

Headers
Copia collegamento

Metrics type counter
Copia collegamento

Options
Copia collegamento

Headers
Copia collegamento

Metric type histogram
Copia collegamento

Options
Copia collegamento

Headers
Copia collegamento

Metric type meter
Copia collegamento

Options
Copia collegamento

Headers
Copia collegamento

Metrics type timer
Copia collegamento

Options
Copia collegamento

Headers
Copia collegamento

MetricsRoutePolicyFactory
Copia collegamento

MetricsMessageHistoryFactory
Copia collegamento

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Rendiamo l’open source più inclusivo

Informazioni su Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Questo contenuto non è disponibile nella lingua selezionata.

Chapter 104. Metrics

Metrics ComponentCopia collegamentoCollegamento copiato negli appunti!

URI formatCopia collegamentoCollegamento copiato negli appunti!

Metric RegistryCopia collegamentoCollegamento copiato negli appunti!

UsageCopia collegamentoCollegamento copiato negli appunti!

HeadersCopia collegamentoCollegamento copiato negli appunti!

Metrics type counterCopia collegamentoCollegamento copiato negli appunti!

OptionsCopia collegamentoCollegamento copiato negli appunti!

HeadersCopia collegamentoCollegamento copiato negli appunti!

Metric type histogramCopia collegamentoCollegamento copiato negli appunti!

OptionsCopia collegamentoCollegamento copiato negli appunti!

HeadersCopia collegamentoCollegamento copiato negli appunti!

Metric type meterCopia collegamentoCollegamento copiato negli appunti!

OptionsCopia collegamentoCollegamento copiato negli appunti!

HeadersCopia collegamentoCollegamento copiato negli appunti!

Metrics type timerCopia collegamentoCollegamento copiato negli appunti!

OptionsCopia collegamentoCollegamento copiato negli appunti!

HeadersCopia collegamentoCollegamento copiato negli appunti!

MetricsRoutePolicyFactoryCopia collegamentoCollegamento copiato negli appunti!

MetricsMessageHistoryFactoryCopia collegamentoCollegamento copiato negli appunti!

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Rendiamo l’open source più inclusivo

Informazioni su Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Metrics Component
Copia collegamento

URI format
Copia collegamento

Metric Registry
Copia collegamento

Usage
Copia collegamento

Headers
Copia collegamento

Metrics type counter
Copia collegamento

Options
Copia collegamento

Headers
Copia collegamento

Metric type histogram
Copia collegamento

Options
Copia collegamento

Headers
Copia collegamento

Metric type meter
Copia collegamento

Options
Copia collegamento

Headers
Copia collegamento

Metrics type timer
Copia collegamento

Options
Copia collegamento

Headers
Copia collegamento

MetricsRoutePolicyFactory
Copia collegamento

MetricsMessageHistoryFactory
Copia collegamento