Logging Configuration

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>%d{yyy.MM.dd HH:mm:ss} %-7([%level])   %logger %msg%n</pattern>
    </encoder>
</appender>

<root level="info">
    <appender-ref ref="STDOUT" />
</root>
...
<!-- silence jetty a bit, because it throws too many messages on INFO. This can be overridden in included files -->
<logger name="org.eclipse.jetty" level ="warn" />

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>%d{yyy.MM.dd HH:mm:ss} %-7([%level])   %logger %msg%n</pattern>
    </encoder>
</appender>

<appender name="server-log" class="ch.qos.logback.core.FileAppender">
   <file>../storage/server.log</file>
   <append>true</append>
   <encoder>
      <pattern>%d{yyy.MM.dd HH:mm:ss} %-7([%level])   %logger %msg%n</pattern>
   </encoder>
</appender>

appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
  <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource">
    <driverClass>com.microsoft.sqlserver.jdbc.SQLServerDriver</driverClass>
    <url>jdbc:sqlserver://HOST:1433;databaseName=MY_DB</url>
    <user>MY_USER</user>
    <password>STRONG_PASSWORD</password>
  </connectionSource>
</appender>


 <root level="info">
    <appender-ref ref="DB" />
 </root>
 ----

=== Rolling File Appender

This appender extends the File Appender with the capability to roll over log files.
It can log to a file named `log.txt` and, once a certain condition is met, the file contents are archived and the file is cleared for new logs.
For more information about configuring the rolling file appender, see xref:advanced-rolling-file-appender-configuration.adoc[].

The RollingFileAppender subcomponent, `RollingPolicy`, is responsible for undertaking the actions required for a rollover.
In addition to `name`, it is necessary to specify:

* `file` - Name of the file where the current logs are stored.
* `fileNamePattern` - Defines the naming pattern of the archived log files.
* `maxFileSize` - Defines the maximum size of the file before creating a new log file.
* `maxHistory` - Defines the number of archived log files preserved.
* `totalSizeCap` - Controls the maximum size of all the archived and the current log file.
It requires the `maxHistory` to be applied first.
* `encoder` - Determines the manner in which an event is written.

.Example configuration
[source,xml]

== Loggers

Defining a logging rule consists of specifying the `name` which is used to process logs from a particular component, severity `level` for which the rule is triggered, and the `appender` to which matched log records should be sent.

=== Simple example

The `root` logger is the default logger that processes all the logs.
It is necessary to specify it in the configuration.
Every other logger has the `logger` name.

The following logger named `org.apache.activemq` processes all logs from the `org.apache.activemq` class with the `WARN` severity level and then sends them to the `stdout` and `server-log` appenders.
Attributes that must be defined are:

* `name` - The name of the logger.
It is usually the name of the class you wish to log.
* `level` - The severity level for which the rule is triggered.
Possible levels are `DEBUG`, `INFO`, `WARN`, `ERROR`.
* `additivity` - Defines whether the ancestor logger (or root) logs the messages from the defined logger.
To turn this behavior off, set additivity to `false`.
If `true`, the event can be logged multiple times (by parent loggers).
* `appender-ref` - Specifies which appenders should be used.
It needs to be specified with the attribute `ref` and the appender name from the appender defined in the configuration.

[source,xml]

This root logger would catch a log record like the following:

[source,xml]

== Full configuration example

The following example shows several appenders specified and commented out.
In order to use them, uncomment the appender you wish to configure.

IMPORTANT: When defining where logs should be stored, you need to provide absolute file paths.
Otherwise, the log files are not created.

[source,xml]

== Useful hints

For more information, see the official https://logback.qos.ch/documentation.html[Logback documentation^].

=== Configuration

Basic logging configuration (like in the previous example) can be found bundled within the product Java libraries.

* To extend the basic configuration, put the `logback-extension.xml` file into the `workdir` of the application.
* To use a custom location for the extension file, you can use Java option `-Dlogging.logbackExtensionFile=<custom_location>/logback-extension.xml`.
* To create a new configuration instead of using the default one, use `-Dlogback.configurationFile=/path/to/config.xml`.

=== Debugging

Use the Java opt `-Dlogback.debug=true` to find useful information for debugging such as which configuration files are used, which were not found, and so on.
This option is very useful during the initial logging setup.

=== Enable logging SQL queries

You can log the SQL queries and their parameters used in JDBC Writer step and Execute SQL tasks in plans and workflows.
The SQL statements are logged separately from the parameters that they take.

To enable this option, the following parameters need to be passed to the Java Virtual Machine:

* `sql.logStatements=true`: Enables logging SQL queries.
* `sql.logMaxParams=20`: Defines how many parameters are logged.
The default value is `20`.
* `sql.logSubstParams=true`: If set to `true`, the runtime logs all queries with a full SQL statement that includes the parameters.
If set to `false`, the runtime logs a short version of the queries that consists only of parameters without the SQL statement.

There are several ways to provide these parameters depending on how you start jobs.
For more information, see the articles xref:jvm-configuration.adoc[] and xref:runtime-properties.adoc[].

The following example shows the expected output in the log file of the task when inserting new rows in a table:

[source,bash]