Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 203. Log Component

Available as of Camel version 1.1

The log: component logs message exchanges to the underlying logging mechanism.

Camel uses sfl4j which allows you to configure logging via, among others:

  • Log4j
  • Logback
  • Java Util Logging

203.1. URI format

log:loggingCategory[?options]

Where loggingCategory is the name of the logging category to use. You can append query options to the URI in the following format, ?option=value&option=value&…​

INFO:*Using Logger instance from the the Registry* As of Camel 2.12.4/2.13.1, if there’s single instance of org.slf4j.Logger found in the Registry, the loggingCategory is no longer used to create logger instance. The registered instance is used instead. Also it is possible to reference particular Logger instance using ?logger=#myLogger URI parameter. Eventually, if there’s no registered and URI logger parameter, the logger instance is created using loggingCategory.

For example, a log endpoint typically specifies the logging level using the level option, as follows:

log:org.apache.camel.example?level=DEBUG

The default logger logs every exchange (regular logging). But Camel also ships with the Throughput logger, which is used whenever the groupSize option is specified.

TIP:*Also a log in the DSL* There is also a log directly in the DSL, but it has a different purpose. Its meant for lightweight and human logs. See more details at LogEIP.

203.2. Options

The Log component supports 2 options which are listed below.

NameDescriptionDefaultType

exchangeFormatter (advanced)

Sets a custom ExchangeFormatter to convert the Exchange to a String suitable for logging. If not specified, we default to DefaultExchangeFormatter.

 

ExchangeFormatter

resolveProperty Placeholders (advanced)

Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.

true

boolean

The Log endpoint is configured using URI syntax:

log:loggerName

with the following path and query parameters:

203.2.1. Path Parameters (1 parameters):

NameDescriptionDefaultType

loggerName

Required The logger name to use

 

String

203.2.2. Query Parameters (26 parameters):

NameDescriptionDefaultType

groupActiveOnly (producer)

If true, will hide stats when no new messages have been received for a time interval, if false, show stats regardless of message traffic.

true

Boolean

groupDelay (producer)

Set the initial delay for stats (in millis)

 

Long

groupInterval (producer)

If specified will group message stats by this time interval (in millis)

 

Long

groupSize (producer)

An integer that specifies a group size for throughput logging.

 

Integer

level (producer)

Logging level to use. The default value is INFO.

INFO

String

logMask (producer)

If true, mask sensitive information like password or passphrase in the log.

 

Boolean

marker (producer)

An optional Marker name to use.

 

String

synchronous (advanced)

Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).

false

boolean

maxChars (formatting)

Limits the number of characters logged per line.

10000

int

multiline (formatting)

If enabled then each information is outputted on a newline.

false

boolean

showAll (formatting)

Quick option for turning all options on. (multiline, maxChars has to be manually set if to be used)

false

boolean

showBody (formatting)

Show the message body.

true

boolean

showBodyType (formatting)

Show the body Java type.

true

boolean

showCaughtException (formatting)

f the exchange has a caught exception, show the exception message (no stack trace). A caught exception is stored as a property on the exchange (using the key link org.apache.camel.ExchangeEXCEPTION_CAUGHT and for instance a doCatch can catch exceptions.

false

boolean

showException (formatting)

If the exchange has an exception, show the exception message (no stacktrace)

false

boolean

showExchangeId (formatting)

Show the unique exchange ID.

false

boolean

showExchangePattern (formatting)

Shows the Message Exchange Pattern (or MEP for short).

true

boolean

showFiles (formatting)

If enabled Camel will output files

false

boolean

showFuture (formatting)

If enabled Camel will on Future objects wait for it to complete to obtain the payload to be logged.

false

boolean

showHeaders (formatting)

Show the message headers.

false

boolean

showOut (formatting)

If the exchange has an out message, show the out message.

false

boolean

showProperties (formatting)

Show the exchange properties.

false

boolean

showStackTrace (formatting)

Show the stack trace, if an exchange has an exception. Only effective if one of showAll, showException or showCaughtException are enabled.

false

boolean

showStreams (formatting)

Whether Camel should show stream bodies or not (eg such as java.io.InputStream). Beware if you enable this option then you may not be able later to access the message body as the stream have already been read by this logger. To remedy this you will have to use Stream Caching.

false

boolean

skipBodyLineSeparator (formatting)

Whether to skip line separators when logging the message body. This allows to log the message body in one line, setting this option to false will preserve any line separators from the body, which then will log the body as is.

true

boolean

style (formatting)

Sets the outputs style to use.

Default

OutputStyle

203.3. Regular logger sample

In the route below we log the incoming orders at DEBUG level before the order is processed:

from("activemq:orders").to("log:com.mycompany.order?level=DEBUG").to("bean:processOrder");

Or using Spring XML to define the route:

<route>
  <from uri="activemq:orders"/>
  <to uri="log:com.mycompany.order?level=DEBUG"/>
  <to uri="bean:processOrder"/>
</route>

203.4. Regular logger with formatter sample

In the route below we log the incoming orders at INFO level before the order is processed.

from("activemq:orders").
    to("log:com.mycompany.order?showAll=true&multiline=true").to("bean:processOrder");

203.5. Throughput logger with groupSize sample

In the route below we log the throughput of the incoming orders at DEBUG level grouped by 10 messages.

from("activemq:orders").
    to("log:com.mycompany.order?level=DEBUG&groupSize=10").to("bean:processOrder");

203.6. Throughput logger with groupInterval sample

This route will result in message stats logged every 10s, with an initial 60s delay and stats should be displayed even if there isn’t any message traffic.

from("activemq:orders").
    to("log:com.mycompany.order?level=DEBUG&groupInterval=10000&groupDelay=60000&groupActiveOnly=false").to("bean:processOrder");

The following will be logged:

"Received: 1000 new messages, with total 2000 so far. Last group took: 10000 millis which is: 100 messages per second. average: 100"

203.7. Masking sensitive information like password

Available as of Camel 2.19

You can enable security masking for logging by setting logMask flag to true. Note that this option also affects Log EIP.

To enable mask in Java DSL at CamelContext level:

camelContext.setLogMask(true);

And in XML:

<camelContext logMask="true">

You can also turn it on|off at endpoint level. To enable mask in Java DSL at endpoint level, add logMask=true option in the URI for the log endpoint:

from("direct:start").to("log:foo?logMask=true");

And in XML:

<route>
  <from uri="direct:foo"/>
  <to uri="log:foo?logMask=true"/>
</route>

org.apache.camel.processor.DefaultMaskingFormatter is used for the masking by default. If you want to use a custom masking formatter, put it into registry with the name CamelCustomLogMask. Note that the masking formatter must implement org.apache.camel.spi.MaskingFormatter.

203.8. Full customization of the logging output

Available as of Camel 2.11

With the options outlined in the #Formatting section, you can control much of the output of the logger. However, log lines will always follow this structure:

Exchange[Id:ID-machine-local-50656-1234567901234-1-2, ExchangePattern:InOut,
Properties:{CamelToEndpoint=log://org.apache.camel.component.log.TEST?showAll=true,
CamelCreatedTimestamp=Thu Mar 28 00:00:00 WET 2013},
Headers:{breadcrumbId=ID-machine-local-50656-1234567901234-1-1}, BodyType:String, Body:Hello World, Out: null]

This format is unsuitable in some cases, perhaps because you need to…​

  • …​ filter the headers and properties that are printed, to strike a balance between insight and verbosity.
  • …​ adjust the log message to whatever you deem most readable.
  • …​ tailor log messages for digestion by log mining systems, e.g. Splunk.
  • …​ print specific body types differently.
  • …​ etc.

Whenever you require absolute customization, you can create a class that implements the ExchangeFormatter interface. Within the format(Exchange) method you have access to the full Exchange, so you can select and extract the precise information you need, format it in a custom manner and return it. The return value will become the final log message.

You can have the Log component pick up your custom ExchangeFormatter in either of two ways:

Explicitly instantiating the LogComponent in your Registry:

<bean name="log" class="org.apache.camel.component.log.LogComponent">
   <property name="exchangeFormatter" ref="myCustomFormatter" />
</bean>

203.8.1. Convention over configuration:*

Simply by registering a bean with the name logFormatter; the Log Component is intelligent enough to pick it up automatically.

<bean name="logFormatter" class="com.xyz.MyCustomExchangeFormatter" />
Note

the ExchangeFormatter gets applied to all Log endpoints within that Camel Context. If you need different ExchangeFormatters for different endpoints, just instantiate the LogComponent as many times as needed, and use the relevant bean name as the endpoint prefix.

From Camel 2.11.2/2.12 onwards when using a custom log formatter, you can specify parameters in the log uri, which gets configured on the custom log formatter. Though when you do that you should define the "logFormatter" as prototype scoped so its not shared if you have different parameters, eg:

<bean name="logFormatter" class="com.xyz.MyCustomExchangeFormatter" scope="prototype"/>

And then we can have Camel routes using the log uri with different options:

<to uri="log:foo?param1=foo&amp;param2=100"/>

<to uri="log:bar?param1=bar&amp;param2=200"/>

203.9. Using Log component in OSGi

Improvement as of Camel 2.12.4/2.13.1

When using Log component inside OSGi (e.g., in Karaf), the underlying logging mechanisms are provided by PAX logging. It searches for a bundle which invokes org.slf4j.LoggerFactory.getLogger() method and associates the bundle with the logger instance. Without specifying custom org.sfl4j.Logger instance, the logger created by Log component is associated with camel-core bundle.

In some scenarios it is required that the bundle associated with logger should be the bundle which contains route definition. To do this, either register single instance of org.slf4j.Logger in the Registry or reference it using logger URI parameter.

203.10. See Also

  • LogEIP for using log directly in the DSL for human logs.