Page History

Tracer Interceptor

Camel supports a tracer interceptor that is can be used for logging, at the route executions at INFO level, a route's execution. The Tracer tracer is an InterceptStrategy which instance of org.apache.camel.spi.InterceptStrategy. It can be applied to a either a DefaultCamelContext or a SpringCamelContext to ensure that there is a a TracerInterceptor created for every node in the DSL.You can enable or disable the Tracerroute. The tracer's logging can be enabled/disabled dynamically , by calling the tracer's setEnabled its setEnabled method.

Tip

title	Logging dependencies

Checkout which dependencies are required by Camel for logging purpose.

Info
From Camel 2.12

...

: the CamelContext must be explicitly configured for tracing:

XML: <camelContext trace="true" ...>

...

Java

...

: camelContext.setTracing(true).

Options

Div

class	confluenceTableSmall

Option	Default	Description
formatter`destinationUri`	`null`	Optional destination URI to route TraceEventExchange containing TraceEventMessage with details about the trace. Can be used for custom processing to store traces in database using JPA.
`enabled`	`true`	Enable/disable the tracer.
`formatter`		Sets the Trace Formatter to use. Default:		Sets the Trace Formatter to use. Will default use `org.apache.camel.processor.interceptor.DefaultTraceFormatter`.
enabled`jpaTraceEventMessageClassName`	true	`null`	Camel 2.3: Fully qualified class name for a custom `org.apache.camel.processor.interceptor.TraceEventMessage` class which contains the traced information. For example you can use your custom JPA @Entity class to store traced information in a database according to your schema layout.Flag to enable or disable this tracer
`logLevel`	`INFO`	The logging level to use: `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `OFF`
`logName`		The log name to use. Default: Will default use `org.apache.camel.processor.interceptor.TraceInterceptor`.
traceFilter`logStackTrace`	`false`	Controls whether the stack trace of a traced exception should be logged. If `false` only the exception's class and message are logged.
`traceFilter`	`null`	An Exchange	null	An exchange Predicate to filter the tracing.
`traceInterceptors`	`false`	Flag to enable or Enable/disable tracing of interceptors.
`traceExceptions`	`true`	Flag to enable or disable tracing of thrown exception during processing of the exchangeExchange.
traceOutExchanges`traceHandler`	false	Flag to enable fine grained tracing with a callback for both IN (before) and OUT (after). Is disabled by default which means there is only one trace callback executed.
logStackTrace	false	When tracing exception you can control whether the stack trace should be logged also. If not then only the exception class and message is logged.
useJpa	false	To use a `JpaTraceEventMessage` from camel-jpa component as the `TraceEventMessage`. This requires that camel-jpa.jar is on the classpath.
destinationUri	null	Optional destination uri to route TraceEventExchange containing TraceEventMessage with details about the trace. Can be used for custom processing to store traces in database using JPA.
jpaTraceEventMessageClassName	null	Camel 2.3: Fully class name for a custom `org.apache.camel.processor.interceptor.TraceEventMessage` class which contains the traced information. For example you can use your custom JPA @Entity class to store traced information in a database according to your schema layout.
`null`	Camel 2.3: To use	traceHandler	null	Camel 2.3: To use a custom `org.apache.camel.processor.interceptor.TraceEventHandler` where you can control what happens when a trace event occurs.
`traceInterceptorFactory`	`null`	Camel 2.3: To use a custom `org.apache.camel.processor.interceptor.TraceInterceptorFactory` where you can create the runtime trace instance which does the actual tracing. It should be a `Processor` instance. The default tracer is implemented in the class `org.apache.camel.processor.interceptor.TraceInterceptor`.be a `Processor` instance. Default: `org.apache.camel.processor.interceptor.TraceInterceptor`.
`traceOutExchanges`	`false`	Flag to enable fine grained tracing with a callback for both `IN` (before) and `OUT` (after). By default only one trace callback is executed.
`useJpa`	`false`	To use a `JpaTraceEventMessage` from camel-jpa component as the `TraceEventMessage`. This requires that camel-jpa.jar is on the classpath.

Formatting

The tracer formats the execution of exchanges to log lines. They are logged at at INFO level in the log category: org.apache.camel.processor.interceptor.TraceInterceptor.
The tracer uses by By default the tracer uses: org.apache.camel.processor.interceptor.DefaultTraceFormatter to format the log line.

DefaultTraceFormatter has the following options:

Div

class	confluenceTableSmall

Camel 2.18: If true, each piece of information is logged on a new line

Option	Default	Description
`breadCrumbLength`	`0`	Fixed length of the bread crumb. `0` = no fixed length. Setting a value to e.g. `80` allows the tracer logs to be aligned for easier readinglogs to be aligned for easier reading.
`maxChars`		Limits the number of chars logged per line. From Camel 2.9: the default value is `10000`.
`multiline`	`false`	Camel 2.18: If `true` each piece of information is logged on a new line.
`nodeLength`	`0`	Fixed length of the node. `0` = no fixed length. Setting a value to e.g. `40` allows the tracer logs to be aligned for easier reading.
`showBody`	`true`	Output the `IN` body.
`showBodyType`	`true`	Output the `IN` body Java type.
`showBreadCrumb`	`true`	Outputs the unique unit of work (UOW) for the exchange. To be used for correlation so you can identify the same exchangeExchange.
showNode`showException`	`true`Previous and destination node, so you can see from -> to	Output the exception if the exchange has failed.
`showExchangeId`	`false`	To output the unique exchange `id`. Currently the breadcrumb is sufficient.
showShortExchangeId	false	To output the unique exchange id in short form, without the hostname.
showProperties	false	Output the exchange properties
showHeaders`showExchangePattern`	`true`	Output the in message headers
showBodyType	true	Output the in body Java type
Message Exchange Pattern (MEP).
`showHeaders`showBody	`true`	Output the in body
showOutHeaders	false	Output the out (if any) message headers
the `IN` message headers.
`showNode`	`true`	Previous and destination node. Displayed as: `from -> to`.
`showOutBody`showOutBodyType	`false`	Output the out the `OUT` (if any) body Java type.
showOutBody`showOutBodyType`	`false`	Output the out the `OUT` (if any) body
showExchangePattern	true	Output the exchange pattern
showException	true	Output the exception if the exchange has failed
showRouteId	true	Camel 2.8: Output the id of the route
maxChars		Is used to limit the number of chars logged per line. The default value is `10000` from Camel 2.9 onwards.
Java type.
`showOutHeaders`	`false`	Output the `OUT` (if any) message headers.
`showProperties`	`false`	Output the Exchange's properties.
`showRouteId`	`true`	Camel 2.8: output the `id` of the route.
`showShortExchangeId`	`false`	To output the Exchange's unique `id` in short form, without the hostname	multiline	false	.

Tip

title	Logging stream bodies

From Camel 2.8: the Camel Tracer will by default not log stream or files bodies from Camel 2.8 onwards. You can . To force Camel to log those by setting these set the following property on the CamelContext properties:

Code Block

language	java

camelContext.getProperties().put(Exchange.LOG_DEBUG_BODY_STREAMS, true);

...

Code Block
ID-claus-acer/4412-1222625653890/2-0 -> to(mock:a) , Pattern:InOnly , Headers:{to=James} , BodyType:String , Body:Hello London

where:

ID-claus-acer/3690-1214458315718/2-0 is the breadcrumb with the unique correlation id.
node3 is the id of the node in the route path.

...

Always displayed.
To[mock:a] is the destination node.
InOnly is the exchange pattern. Is always shown.
Then the rest is properties, headers and the body.

Showing Showing `from` and and `to`

The trace log will output both the from and to so you can see where the Exchange came from, such as:

...

To enable tracer from the main run:

Code Block
java org.apache.camel.spring.Main -t

...

and the tracer will be active.

Enabling

...

in Java

...

Code Block

language	java

context.setTracing(true);

...

Code Block

INFO  TraceInterceptor     - ID-davsclaus-local-54403-1246038742624-0-0 >>> from(direct:start) --> MyProcessor     , Pattern:InOnly, Headers:{to=James}, BodyType:String, Body:Hello London
INFO  TraceInterceptor     - ID-davsclaus-local-54403-1246038742624-0-0 >>> MyProcessor --> mock:a                 , Pattern:InOnly, Headers:{to=James}, BodyType:String, Body:Hello London
INFO  TraceInterceptor     - ID-davsclaus-local-54403-1246038742624-0-0 >>> mock:a --> mock:b                      , Pattern:InOnly, Headers:{to=James}, BodyType:String, Body:Hello London
...
INFO  TraceInterceptor     - ID-davsclaus-local-54403-1246038742624-0-1 >>> from(direct:start) --> MyProcessor     , Pattern:InOnly, Headers:{from=Claus}, BodyType:String, Body:This is Copenhagen calling
INFO  TraceInterceptor     - ID-davsclaus-local-54403-1246038742624-0-1 >>> MyProcessor --> mock:a                 , Pattern:InOnly, Headers:{from=Claus}, BodyType:String, Body:This is Copenhagen calling
INFO  TraceInterceptor     - ID-davsclaus-local-54403-1246038742624-0-1 >>> mock:a --> mock:b                      , Pattern:InOnly, Headers:{from=Claus}, BodyType:String, Body:This is Copenhagen calling

Configuring

...

in Java

...

The tracer options can be configured from the Java DSL like this:

Code Block

language	java

    public void configure() throws Exception {
        // add tracer as an interceptor so it will log the exchange executions at runtime
        // this can aid us to understand/see how the exchanges is routed etc.
        Tracer tracer = new Tracer();
        formatter.getDefaultTraceFormatter().setShowBreadCrumb(false);
        formatter.getDefaultTraceFormatter().setShowNode(false);
        ...
        getContext().addInterceptStrategy(tracer);

Using

...

Predicates to

...

Filter Exchanges

In the code below we want the tracer only to trace if the body contains the text London. As this is just an example can of course set any Predicate that matches your criteria:

Code Block

	java
	java

    Tracer tracer = new Tracer();
    // set the level to FATAL so we can easily spot it
    tracer.setLogLevel(LoggingLevel.FATAL);
    // and only trace if the body contains London as text
    tracer.setTraceFilter(body().contains(constant("London")));

Enabling

...

in Spring XML

There is now a a trace attribute you can specify on the *the <camelContext/> for example.

Example:

Code Block

language	xml

  <camelContext trace="true" xmlns="http://activemq.apache.org/camel/schema/spring">
    ...
  </camelContext>

...

Another option is to just include a spring XML which defines the Tracer bean such as the one that is automatically included if you run the Main with -t above.

...

Configuring in Spring XML

You can configure the tracer as a Spring bean. Just add a bean with the bean class org.apache.camel.processor.interceptor.Tracer and Camel will use it as the Tracertracer.

Wiki Markup
{snippet:id=e1\|lang=xml\|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/interceptor/tracerConfigurationTest.xml}

You can configure the formatting of tracer as a Spring bean. Just add a bean with the id traceFormatter and Camel will lookup this this id and use the formatter, as the example below illustrates:

Wiki Markup
{snippet:id=e1\|lang=xml\|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/interceptor/traceFormatterTest.xml}

Enable

...

Tracing of `out`

...

Messages

You can trace messages coming out of processing steps. To enable this, configure the tracer as follows:

Wiki Markup
{snippet:id=tracingOutExchanges\|title=Java DSL\|lang=java\|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/TraceInterceptorWithOutBodyTraceTest.java}

or

Wiki Markup
{snippet:id=tracingOutExchanges\|title=Spring DSL\|lang=xml\|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/processor/traceInterceptorWithOutBodyTrace.xml}

Running with these options, you'll get output similar to:

Code Block

INFO  TraceInterceptor - ID-mojo/59899-1225474989226/2-0 -> transform(body) , Pattern:InOnly , Headers:{to=James} , BodyType:String , Body:Hello London
INFO  TraceInterceptor - transform(body) -> ID-mojo/59899-1225474989226/2-0 , Pattern:InOnly , Headers:{to=James} , BodyType:String , Body:Hello London , OutBodyType:String , OutBody:Hello London

Using a Custom Formatter

You can now implement your own org.apache.camel.processor.interceptor.TraceFormatter to be used for logging trace messages to the log.

The sample example below shows how to configure a Tracer from Java DSL using custom formatter:

Wiki Markup
{snippet:id=e1\|lang=java\|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/TraceFormatterTest.java}

And here we have our custom logger that implements the TraceFormatter interface where we can construct the log message how we like:

Wiki Markup
{snippet:id=e2\|lang=java\|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/TraceFormatterTest.java}

Using a Destination for

...

Custom Processing and

...

Routing

Tracer supports custom processing of trace events. This can be used to route a trace event to a JPA endpoint for persistence in a database.

...

snapshot of the original traced Exchange as a immutable TraceEventMessage containing String values of the fields, when the interception occurred. This ensures the fields contains the exact data at the given time of interception.
the original Exchange can in some implementations be accessed using getTracedExchange() (though with JPA based tracer you cannot get the original Exchange).

Warning
Beware to access the original Exchange to avoid causing any side effects or alter its state. Prefer to access the information from TraceEventMessage

Camel routes the the TraceEventMessage synchronously from the point of interception. When its completed Camel will continue routing the original Exchange.

The sample below demonstrates this feature, where we route traced Exchanges to the direct:traced route:

Wiki Markup
{snippet:id=e1\|lang=java\|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/TraceInterceptorDestinationTest.java}

Then we can configure a route for the traced messages:

Code Block
from("direct:traced") .process(new MyTraceMessageProcessor()) .to("file://myapp/logs/trace);

And our processor where we can process the TraceEventMessage. Here we want to create a CSV format of the trace event to be stored as a file. We do this by constructing the CSV String and the replace the the IN body with our String instead of the TraceEventMessage.

Wiki Markup
{snippet:id=e2\|lang=java\|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/TraceInterceptorDestinationTest.java}

Using JPA as

...

a Datastore for Trace Messages

See Tracer Example for complete documentation and how to use this feature.

Traced

...

Route Path During Runtime

Tracer also traces the actual route path taken during runtime. Camel will store the route path taken on the UnitOfWork when Tracer is enabled. The example below demonstrates how we can use that for error handling where we can determine at which node in the route graph the error triggered.

First we define our route:

Wiki Markup
{snippet:id=e1\|lang=java\|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/TraceableUnitOfWorkTest.java}

And then our custom error processor where we can handle the exception and figure out at which node the exception occurred.

Wiki Markup
{snippet:id=e2\|lang=java\|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/TraceableUnitOfWorkTest.java}

...

Child pages

Versions Compared

Old Version 61

New Version 62

Key

Tracer Interceptor

Options

Formatting

Showing Showing `from` and and `to`

Enabling

in Java

Configuring

in Java

Using

Predicates to

Filter Exchanges

Enabling

in Spring XML

Configuring in Spring XML

Enable

Tracing of `out`

Messages

Using a Custom Formatter

Using a Destination for

Custom Processing and

Routing

Using JPA as

a Datastore for Trace Messages

Traced

Route Path During Runtime

Child pages

Page History

Versions Compared

Old Version 61

New Version 62

Key

Tracer Interceptor

Options

Formatting

Showing Showing from and and to

Enabling

in Java

Configuring

in Java

Using

Predicates to

Filter Exchanges

Enabling

in Spring XML

Configuring in Spring XML

Enable

Tracing of out

Messages

Using a Custom Formatter

Using a Destination for

Custom Processing and

Routing

Using JPA as

a Datastore for Trace Messages

Traced

Route Path During Runtime

Showing Showing `from` and and `to`

Tracing of `out`