Overview

Since version v1.5.3100-beta of the JobScheduler Engine it is possible to configure a logging API of your choice to handle the log messages from JobScheduler (assumed the logging API is supported by slf4j). Using this feature you have a wide range of possibilities to handle your logs, e.g. filtering, mailing, eventing etc.

JobScheduler was currently shipped with the nop-api for slf4j. That means that no messages from JobScheduler logged via a logging api.

But beside the configuration of a logging API such as logback or log4j the logging in the "old style" is supported until further notice. That means that you will always find the scheduler logs and the logs of your jobs in the folder logs located of your JobScheduler installation.

Installation in general

Have a look at factory.ini to will find a property like class_path in the java section:

 class_path = ${SCHEDULER_HOME}/lib/*.jar:${SCHEDULER_HOME}/lib/hibernate/*.jar:${SCHEDULER_HOME}/lib/jetty_ext/*.jar:${SCHEDULER_HOME}/lib/log/nop/*.jar

This is the place where you can subtitute the nop api with a real logging api like logback.

Put the necessary libraries for the logging api of your choice into a separate folder and point to the jars of this folder in factory.ini instead to ${SCHEDULER_HOME}/lib/log/nop/*.jar.

Relationship between the configuration for the logging API and factory.ini

The setting of the property log_level in the factory.ini filters the messages that will be available for slf4j. That means, that the level you set in the factory.ini should never be higher than the level you have specified in the logger JobScheduler. If you want full control of all log messages from JobScheduler then you should specify

 log_level = debug9

in factory.ini but be aware the log files can be very large in this case.

The setting of the property log in the factory.ini file causes the Job Scheduler to write a detailed protocol. This protocol is intended for use in problem diagnosis. The file name should be specified here as a full path. A plus character + written directly before the file name causes an already existing protocol to be continued. Otherwise such a protocol will be overwritten.

Examples:

 log = ${SCHEDULER_DATA}/logs/scheduler.log

 log = file_name scheduler.log file name
 log = +${SCHEDULER_DATA}/logs/scheduler.log     # Continue existing protocol

Using log4j

To configure log4j for the JobScheduler Engine add a log4j configuration file (log4j.properties) to a directory of your choice and reference it by setting the java system property log4j.configuration, e.g. -Dlog4j.configuration=file:///path/to/log4j.properties.

Installation

Create the folder ./lib/log/log4j in the installation path of JobScheduler you should modify the property class_path as follows:

 class_path = ${SCHEDULER_HOME}/lib/*.jar:${SCHEDULER_HOME}/lib/hibernate/*.jar:${SCHEDULER_HOME}/lib/jetty_ext/*.jar:${SCHEDULER_HOME}/lib/log/log4j/*.jar

The folder log4j has to contain the slf4j-log4j12-x.jar file, e.g. slf4j-log4j12-1.7.5.jar.
Make sure that log4j-1.2.16.jar is located in the ./lib directory.

Sample configuration

log4j.rootLogger=info, stdout, FILE
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%5p [%t] (%F:%L) - %m%n

# Configuration File
log4j.appender.FILE=org.apache.log4j.FileAppender
log4j.appender.FILE.File=$\{java.io.tmpdir\}/log4j-test.log
log4j.appender.FILE.Append=true
log4j.appender.FILE.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE.layout.ConversionPattern=%5p [%t] (%F:%L) - %m%n

Starting with Release 1.13.3 the configuration looks like this

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
	<Appenders>
        <Console name="stdout" target="SYSTEM_OUT">
			<PatternLayout pattern="[%5p] (%F:%L) - %m%n"/>
		</Console>
        <!-- Example Rolling File Appender -->
        <RollingFile name="ExampleAppender" fileName="${env:SCHEDULER_DATA}/logs/example.log" 
		   createOnDemand="true" filePattern="${env:SCHEDULER_DATA}/logs/example-%d{yyyy-MM}-%i.log.gz">
            <PatternLayout pattern="%d{ISO8601} %c [%-5p] - %m%n" charset="UTF-8"/>
            <Policies>
                <TimeBasedTriggeringPolicy/>
                <SizeBasedTriggeringPolicy size="20MB"/>
            </Policies>
            <DefaultRolloverStrategy fileIndex="10"/>
        </RollingFile>
    </Appenders>
	<Loggers>
		<Root level="error">
            <AppenderRef ref="stdout"/>
            <AppenderRef ref="ExampleAppender"/>
		</Root>
        <Logger name="joe" level="info"  additivity="false" >
            <AppenderRef ref="ExampleAppender"/>
        </Logger>
    </Loggers>
</Configuration>

Start of JobScheduler

To use the configuration above you have to start JobScheduler by setting the options property (section [java]) in your ./config/factory.ini, e.g.

 [java]
 options = -Dlog4j.configuration=file://path/to/log4j.properties

Starting with Release 1.13.3

 [java]
 options = -Dlog4j.configurationFile=file://path/to/log4j2.xml

Logging to a syslog server

Log4j offers a SyslogAppender to send log entries to a syslog receiver. This Appender is not explicitely tested by us but it seems to be straight foward to use this appender.

Example

log4j.rootLogger=info, SYSLOG
log4j.appender.SYSLOG=org.apache.log4j.net.SyslogAppender
log4j.appender.SYSLOG.syslogHost=localhost
log4j.appender.SYSLOG.layout=org.apache.log4j.PatternLayout
log4j.appender.SYSLOG.layout.conversionPattern=%5p [%t] (%F:%L) - %m%n

Using logback: To configure logback for the JobScheduler Engine put a logback configuration file into a directory of your choice and reference it by setting the java system property logback.configurationFile, e.g. -Dlogback.configurationFilefilename

Installation

As described above you have to create a separate folder containing the required jar files to use logback. Assuming your are creating the folder lib/log/logback in the installation path of JobScheduler then you should modify the property class_path as follows:

 class_path = ${SCHEDULER_HOME}/lib/*.jar:${SCHEDULER_HOME}/lib/hibernate/*.jar:${SCHEDULER_HOME}/lib/jetty_ext/*.jar:${SCHEDULER_HOME}/lib/log/logback/*.jar

The folder logback has to contain at least logback-core and logback-classic, e.g.

• logback-classic-1.0.11.jar
• logback-core-1.0.11.jar

Sample configuration

<configuration>

   <appender name="STDERR" class="ch.qos.logback.core.ConsoleAppender">
       <encoder>
           <pattern>%d{dd HH:mm:ss} [%thread] %-5level %logger - %msg%n</pattern>
       </encoder>
   </appender>
   
   <appender name="FILE" class="ch.qos.logback.core.FileAppender">
       <file>${user.dir}/logs/logback-test.log</file>
       <append>true</append>
       <encoder>
           <pattern>%d{dd HH:mm:ss} [%thread] %-5level %logger - %msg%n</pattern>
       </encoder>
   </appender>

   <root level="WARN">
       <appender-ref ref="STDERR" />
   </root>
   
   <logger name="JobScheduler" level="TRACE" additivity="false">
       <appender-ref ref="FILE" />
   </logger>
   
</configuration>

The logger JobScheduler controls the output of the Main Log File (see Logs in the JobScheduler documentation for details).

Please note that the file element of a FileAppender can not contain a relative path (see do not use relative path with logback for details).

Start of JobScheduler

To use the configuration above you have to start JobScheduler by setting the options property (section [java]) in your ./config/factory.ini, e.g.

 [java]
 options = -Dlogback.configurationFile=${SCHEDULER_DATA}/config/logback.xml

Logging to a syslog server

Logback offers a SyslogAppender to send log entries to a syslog receiver. This Appender is not explicitely tested by us but it seems to be straight foward to use this appender.

See Appenders in the logback manual for details.

Mapping of the JobScheduler log levels

The log levels used by JobScheduler are mapped as follows (highest to lowest):