Tracer Interceptor

Camel supports a tracer interceptor that is used for logging the route executions at INFO level.

The Tracer is an InterceptStrategy which can be applied to a DefaultCamelContext or SpringCamelContext to ensure that there is a TracerInterceptor created for every node in the DSL.

You can enable or disable the Tracer's logging dynamically, by calling the tracer's setEnabled method.

Logging dependencies

Icon

Checkout which dependencies are required by Camel for logging purpose.

From Camel 2.12 onwards you must explicit enable tracing on CamelContext to use it. In XML DSL you do this by setting <camelContext trace="true" ...> and in Java you do camelContext.setTracing(true).

Options

Option

Default

Description

formatter

 

Sets the Trace Formatter to use. Will default use org.apache.camel.processor.interceptor.DefaultTraceFormatter.

enabled

true

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. Will default use org.apache.camel.processor.interceptor.TraceInterceptor.

traceFilter

null

An exchange Predicate to filter the tracing.

traceInterceptors

false

Flag to enable or disable tracing of interceptors

traceExceptions

true

Flag to enable or disable tracing of thrown exception during processing of the exchange

traceOutExchanges

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.

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.

Formatting

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.
The tracer uses by default the org.apache.camel.processor.interceptor.DefaultTraceFormatter to format the log line.

DefaultTraceFormatter has the following options:

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

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.

showBreadCrumb

true

Outputs the unique unit of work for the exchange. To be used for correlation so you can identify the same exchange.

showNode

true

Previous and destination node, so you can see from -> to.

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

true

Output the in message headers

showBodyType

true

Output the in body Java type

showBody

true

Output the in body

showOutHeaders

false

Output the out (if any) message headers

showOutBodyType

false

Output the out (if any) body Java type

showOutBody

false

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

Logging stream bodies

Icon

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

Example:

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. Is always shown.
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:

Enabling

To enable tracer from the main run

or

and the tracer will be active.

Enabling from Java DSL

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 tracer for one particular route.

Configuring from Java DSL

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

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:

Enabling from Spring XML

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

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.

Configuration from Spring

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.

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 formatter, as the example below illustrates:

Enable tracing of out messages

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

Java DSL

or

Spring DSL

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

Using 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 below shows how to configure a Tracer from Java DSL using custom formatter:

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

Using 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).
Icon

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:

Then we can configure a route for the traced messages:

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.

Using JPA as 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:

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

See Also

© 2004-2014 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