Since we're on a major migration process of this website, some component documents here are out of sync right now. In the meantime you may want to look at the early version of the new website
We would very much like to receive any feedback on the new site, please join the discussion on the Camel user mailing list.

Tracer Interceptor

Implementing custom tracing via TracingInterceptor has been deprecated. However turning tracing on via setTracing(true) is okay.


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

Logging dependencies

Checkout which dependencies are required by Camel for logging purpose.

From Camel 2.12: the CamelContext must be explicitly configured for tracing:

  • XML:  <camelContext trace="true" ...>
  • Java: camelContext.setTracing(true).








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.



Enable/disable the tracer.



Sets the Trace Formatter to use.

Default: org.apache.camel.processor.interceptor.DefaultTraceFormatter.



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.



The logging level to use: FATAL, ERROR, WARN, INFO, DEBUG, TRACEOFF



The log name to use.

Default: org.apache.camel.processor.interceptor.TraceInterceptor.



Controls whether the stack trace of a traced exception should be logged. If false only the exception's class and message are logged.



An Exchange Predicate to filter the tracing.



Enable/disable tracing of interceptors.



Enable/disable tracing of an exception thrown during the processing of an Exchange.



Camel 2.3: To use a custom org.apache.camel.processor.interceptor.TraceEventHandler where you can control what happens when a trace event occurs.



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.

Default: org.apache.camel.processor.interceptor.TraceInterceptor.



Enable/disable fine grained tracing, using a callback, for both IN (before) and OUT (after).

By default only one trace callback is executed.



To use a JpaTraceEventMessage from camel-jpa component as the TraceEventMessage. This requires that camel-jpa.jar is on the classpath.


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

DefaultTraceFormatter has the following options:







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



Limits the number of chars logged per line.

From Camel 2.9: the default value is 10000.



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



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.



Output the IN body.



Output the IN body Java type.



Outputs the unique UnitOfWork for the exchange.

Can be used for correlation to identify a particular Exchange.



Output the exception if the processing of an Exchange has failed.



Enable/disable the output of an Exchange's unique id.

Currently the breadcrumb is sufficient.



Output the Message Exchange Pattern (MEP).



Output the IN message headers.



Previous and destination node.

Displayed as: from -> to.



Output the OUT (if any) body.



Output the OUT (if any) body Java type.



Output the OUT (if any) message headers.



Output the Exchange's properties.



Camel 2.8: output the id of the route.



To output the Exchange's unique id in short form, without the hostname.

Logging stream bodies

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

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


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


  • 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 from and to

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

>>> direct:start --> process(MyProcessor) >>> process(MyProcessor) --> to(mock:a) >>> to(mock:a) --> to(mock:b)


To enable tracer from the main run:

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


java org.apache.camel.spring.Main -trace

and the tracer will be activated.

Enabling in Java


You can configure tracing at a higher granularity as you can configure it on camel context and then override and set it per route as well. For instance you could just enable the tracer for a particular route.

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

Tracer options can be configured in Java as follows:

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:

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 trace attribute you can specify on the <camelContext/>.


xml <camelContext trace="true" xmlns=""> ... </camelContext>

You can see this in action with the SpringTraceTest and its spring.xml file

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 tracer.{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 id and use the associated formatter.


Enable Tracing of OUT Messages

To trace the messages coming out of processing steps configure the tracer as follows:{snippet:id=tracingOutExchanges|title=Java DSL|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/} 

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

With these options the output will look like:

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

To create a custom formatter create a class that implements the interface org.apache.camel.processor.interceptor.TraceFormatter.


And here we have our custom logger that implements the TraceFormatter interface where we can construct the log message how we like:{snippet:id=e2|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/}

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.

This works by Camel creates a new TraceEventMessage containing:

  • 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).

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 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:{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/} 


Then we can configure a route for the traced messages:

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 IN body with our String instead of the TraceEventMessage.{snippet:id=e2|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/interceptor/}

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:{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/}And then our custom error processor where we can handle the exception and figure out at which node the exception occurred.{snippet:id=e2|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/}

See Also

© 2004-2015 The Apache Software Foundation.
Apache Camel, Camel, Apache, the Apache feather logo, and the Apache Camel project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
Graphic Design By Hiram