components/camel-log/src/main/docs/log-component.adoc

[[log-component]]
= Log Component

*Since Camel 1.1*

// HEADER START
*Only producer is supported*
// HEADER END

The Log component logs message exchanges to the underlying logging
mechanism.

Camel uses http://www.slf4j.org/[sfl4j] which allows you to configure
logging via, among others:

* Log4j
* Logback
* Java Util Logging

== URI format

[source]
----
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&...`

[NOTE]
====
*Using Logger instance from the Registry*

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:

[source]
----
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.

== Options



// component options: START
The Log component supports 4 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *exchangeFormatter* (advanced) | Sets a custom ExchangeFormatter to convert the Exchange to a String suitable for logging. If not specified, we default to DefaultExchangeFormatter. |  | ExchangeFormatter
| *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
|===
// component options: END




// endpoint options: START
The Log endpoint is configured using URI syntax:

----
log:loggerName
----

with the following path and query parameters:

=== Path Parameters (1 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *loggerName* | *Required* The logger name to use |  | String
|===


=== Query Parameters (28 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *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
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *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
| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *exchangeFormatter* (advanced) | To use a custom exchange formatter |  | ExchangeFormatter
| *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 org.apache.camel.Exchange#EXCEPTION_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
| *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
|===
// endpoint options: END

// spring-boot-auto-configure options: START
== Spring Boot Auto-Configuration

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

[source,xml]
----
<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-log-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----


The component supports 5 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.component.log.basic-property-binding* | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | Boolean
| *camel.component.log.bridge-error-handler* | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | Boolean
| *camel.component.log.enabled* | Whether to enable auto configuration of the log component. This is enabled by default. |  | Boolean
| *camel.component.log.exchange-formatter* | Sets a custom ExchangeFormatter to convert the Exchange to a String suitable for logging. If not specified, we default to DefaultExchangeFormatter. The option is a org.apache.camel.spi.ExchangeFormatter type. |  | String
| *camel.component.log.lazy-start-producer* | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | Boolean
|===
// spring-boot-auto-configure options: END

== Regular logger sample

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

[source,java]
----
from("activemq:orders").to("log:com.mycompany.order?level=DEBUG").to("bean:processOrder");
----

Or using Spring XML to define the route:

[source,xml]
----
<route>
  <from uri="activemq:orders"/>
  <to uri="log:com.mycompany.order?level=DEBUG"/>
  <to uri="bean:processOrder"/>
</route>
----

== Regular logger with formatter sample

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

[source,java]
----
from("activemq:orders").
    to("log:com.mycompany.order?showAll=true&multiline=true").to("bean:processOrder");
----

== Throughput logger with groupSize sample

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

[source,java]
----
from("activemq:orders").
    to("log:com.mycompany.order?level=DEBUG&groupSize=10").to("bean:processOrder");
----

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

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

The following will be logged:

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

== Masking sensitive information like password
*Since 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:
[source,java]
----
camelContext.setLogMask(true);
----

And in XML:
[source,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:

[source,java]
----
from("direct:start").to("log:foo?logMask=true");
----

And in XML:
[source,xml]
----
<route>
  <from uri="direct:foo"/>
  <to uri="log:foo?logMask=true"/>
</route>
----

`org.apache.camel.support.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`.

== Full customization of the logging output

*Since Camel 2.11*

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

[source]
----
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
http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/spi/ExchangeFormatter.html[`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:*

[source,java]
----
<bean name="log" class="org.apache.camel.component.log.LogComponent">
   <property name="exchangeFormatter" ref="myCustomFormatter" />
</bean>
----

=== Convention over configuration:*

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

[source,xml]
-----
<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.

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:

[source,xml]
----
<bean name="logFormatter" class="com.xyz.MyCustomExchangeFormatter" scope="prototype"/>
----

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

[source,xml]
---------------------------------------------
<to uri="log:foo?param1=foo&amp;param2=100"/>

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

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