Tracer Interceptor
Camel supports a tracer interceptor that is used for logging the route executions at INFO
level.
...
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 The Tracer is an InterceptStrategy which can be applied to a DefaultCamelContext or 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 its setEnabled
method.
...
The org.apache.camel.processor.interceptor.TraceFormatter
has been rename to org.apache.camel.processor.interceptor.DefaultTraceFormatter
in Camel 2.0.
Users of Camel 1.x should use TraceFormatter
whereas 2.x users should use DefaultTraceFormatter
.
...
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)
.
Options
...
Options
...
Option | Default | Description |
---|---|---|
|
| 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: |
...
enabled
...
true
...
|
| Camel 2.3: Fully qualified class name for a custom 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: |
|
| The log name to use. |
...
Default: | ||
|
| Controls whether the stack trace of a traced exception should be logged. If |
|
| 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 |
|
...
| Camel 2. |
...
3: To use a custom Default: | ||
|
| Enable/disable fine grained tracing, using a callback, for both By default only one trace callback is executed. |
|
| To use a |
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 default TraceFormatter
By default the tracer uses: org.apache.camel.processor.interceptor.DefaultTraceFormatter
to format the log line.
TraceFormatter DefaultTraceFormatter
has the following options:
...
Option | Default | Description |
---|---|---|
|
|
...
Fixed length of the bread crumb.
Setting a value to e.g. | ||
|
| Limits the number of chars logged per line. From Camel 2.9: the default value is |
...
|
...
| Camel 2.18: If |
|
|
...
Fixed length of the node.
Setting a value to e.g. | ||
|
| Output the |
|
| Output the |
|
| 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. | |
|
|
...
showProperties
...
Enable/disable the output of an Exchange's unique Currently the breadcrumb is sufficient. |
...
showShortExchangeId
...
false
...
Camel 1.5.1: To output the unique exchange id in short form, without the hostname.
...
|
...
| Output the |
...
Message Exchange Pattern (MEP). | ||
|
| Output |
...
the |
...
|
|
...
Output the in body Java type
...
Previous and destination node. Displayed as: | ||
|
| Output the |
...
showBody
...
true
...
|
|
...
Output the |
...
|
|
...
Camel 2.0: Output the out body
...
Output the | ||
|
| Output the Exchange's properties. |
|
...
| Camel |
...
2. |
...
showException
...
true
...
Camel 1.5: Output the exception if the exchange has failed
Example:
...
8: output the | ||
|
| To output the Exchange's unique |
...
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:
...
Example:
...
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 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 activeactivated.
Enabling
...
The tracer can be enabled by adding it to the interceptor chain to the camel context. This is demonstrated in the unit test below.
Notice: We could have changed the properties on the Tracer object before adding it, if we e.g. don't like the default settings.
Wiki Markup |
---|
{snippet:id=e1|lang=java|url=activemq/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/TraceInterceptorTest.java} |
Running the test we get the trace information logged at INFO level:
...
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.
...
Configuring
...
in Java
...
The tracer Tracer options can be configured from the Java DSL like this:
...
in Java as follows:
...
Using
...
Predicates to
...
Filter Exchanges
Available as of Camel 1.5
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
...
in Spring XML
There is now a a trace
attribute you can specify on the *the <camelContext/>
for example.
...
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.
...
Configuring in Spring
...
XML
You In Camel 1.5 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.
...
tracer.
...
...
Formatting from Spring
You In Camel 1.5 you can configure the formatting of tracer as a Spring bean. Just add a bean with the the id="traceFormatter"
and Camel will lookup this this id
and use the formatter, as the example below illustrates:
...
associated formatter.
Example:
...
Enable
...
Available as of Camel 2.0
Tracing of OUT
Messages
To trace the You can now trace messages coming out of processing steps . To enable this, configure the tracer as follows
...
:
...
...
or
...
...
...
Running with With these options , you'll get output similar to:
...
the output will look like:
...
Using a Custom Formatter
Avaiable as of Camel 2.0
You can now implement your own To create a custom formatter create a class that implements the interface 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:
.
...
Example:
...
And here we have our custom logger that implements the TraceFormatter
interface where we can construct the log message how we like:
...
...
Using a Destination for
...
Custom Processing and Routing
Tracer now 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 TraceEventExchange 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 TraceEventExchange 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 the IN
body with our String instead of the TraceEventMessage
.
...
...
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: