Logging
This page relates to Server logging.
Overview
Genesis uses slf4j for logging. Behind it, the logging backend is log4j2 by default, or Logback if you choose it; see Choosing a logging backend.
Logging is configured by a configuration file for the backend in use. By default this is log4j2-default.xml with log4j2 or logback-default.xml with Logback, and for either backend you can override it with a file of the same name in site-specific/cfg/.
See default files below:
- Log4j2
- Logback
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
<Properties>
<Property name="default-logs" value="${env:GENESIS_HOME}/runtime/logs"/>
<Property name="default-rolling-logs" value="${env:GENESIS_HOME}/runtime/logs/currentRun"/>
</Properties>
<Appenders>
<RollingRandomAccessFile name="RollingFile" fileName="${env:L:-${main:default-logs}}/${sys:PROCESS_NAME}.log"
filePattern="${env:RL:-${main:default-rolling-logs}}/${sys:PROCESS_NAME}_%d{yyyy-MM-dd}-%i.log.gz"
ignoreExceptions="false" append="true" >
<PatternLayout>
<Pattern>%d{dd MMM yyyy HH:mm:ss.SSS} %-4relative [%t] %-5level %logger{35} - %m%n</Pattern>
<header>%d{dd MMM yyyy HH:mm:ss.SSS} %-4relative [%t] INFO logger.config - New ${sys:PROCESS_NAME} log file created\n</header>
</PatternLayout>
<Policies>
<TimeBasedTriggeringPolicy/>
</Policies>
<DefaultRolloverStrategy max="30"/>
</RollingRandomAccessFile>
<RollingFile name="MetricsRollingFile" fileName="${env:L:-${main:default-logs}}/${sys:PROCESS_NAME}.log.metrics"
filePattern="${env:RL:-${main:default-rolling-logs}}/${sys:PROCESS_NAME}_%d{yyyy-MM-dd}-%i.log.metrics.gz"
ignoreExceptions="false" append="true" createOnDemand="true" bufferedIO="true">
<PatternLayout>
<Pattern>%d{dd MMM yyyy HH:mm:ss.SSS} %-4relative [%t] %-5level %logger{35} - %m%n</Pattern>
</PatternLayout>
<Policies>
<TimeBasedTriggeringPolicy/>
</Policies>
<DefaultRolloverStrategy max="30"/>
</RollingFile>
<RollingFile name="RequestLogRollingFile" fileName="${env:L:-${main:default-logs}}/${sys:PROCESS_NAME}.log.request"
filePattern="${env:RL:-${main:default-rolling-logs}}/${sys:PROCESS_NAME}_%d{yyyy-MM-dd}-%i.log.request.gz"
ignoreExceptions="false" append="true" createOnDemand="true" bufferedIO="true">
<PatternLayout>
<Pattern>%d{yyyyMMdd}|%d{HH:mm}|%d{UNIX_MILLIS}|%msg%n</Pattern>
</PatternLayout>
<Policies>
<TimeBasedTriggeringPolicy/>
</Policies>
<DefaultRolloverStrategy max="30"/>
</RollingFile>
</Appenders>
<Loggers>
<AsyncLogger name="global.genesis." level="info" includeLocation="false" additivity="false">
<AppenderRef ref="RollingFile"/>
</AsyncLogger>
<AsyncLogger name="org.apache.commons.configuration2" level="info" includeLocation="false" additivity="false">
<AppenderRef ref="RollingFile"/>
</AsyncLogger>
<AsyncLogger name="org.ehcache" level="info" includeLocation="false" additivity="false">
<AppenderRef ref="RollingFile"/>
</AsyncLogger>
<AsyncLogger name="global.genesis.metrics" level="debug" includeLocation="false" additivity="false">
<AppenderRef ref="MetricsRollingFile"/>
</AsyncLogger>
<AsyncLogger name="global.genesis.net.logging.RequestLogger" level="trace" includeLocation="false" additivity="false">
<LevelRangeFilter minLevel="trace" maxLevel="trace" onMatch="ACCEPT" onMismatch="DENY"/>
<AppenderRef ref="RequestLogRollingFile"/>
</AsyncLogger>
<AsyncRoot level="info" includeLocation="false">
<AppenderRef ref="RollingFile"/>
</AsyncRoot>
</Loggers>
</Configuration>
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="RollingFile" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>${L:-${GENESIS_HOME}/runtime/logs}/${PROCESS_NAME}.log</file>
<append>true</append>
<encoder>
<pattern>%d{dd MMM yyyy HH:mm:ss.SSS} %-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
</encoder>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>${RL:-${GENESIS_HOME}/runtime/logs/currentRun}/${PROCESS_NAME}_%d{yyyy-MM-dd}-1.log.gz</fileNamePattern>
</rollingPolicy>
</appender>
<appender name="MetricsRollingFile" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>${L:-${GENESIS_HOME}/runtime/logs}/${PROCESS_NAME}.log.metrics</file>
<append>true</append>
<encoder>
<pattern>%d{dd MMM yyyy HH:mm:ss.SSS} %-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
</encoder>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>${RL:-${GENESIS_HOME}/runtime/logs/currentRun}/${PROCESS_NAME}_%d{yyyy-MM-dd}-1.log.metrics.gz</fileNamePattern>
</rollingPolicy>
</appender>
<appender name="RequestLogRollingFile" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>${L:-${GENESIS_HOME}/runtime/logs}/${PROCESS_NAME}.log.request</file>
<append>true</append>
<filter class="ch.qos.logback.classic.filter.LevelFilter">
<level>TRACE</level>
<onMatch>ACCEPT</onMatch>
<onMismatch>DENY</onMismatch>
</filter>
<encoder>
<pattern>%d{yyyyMMdd}|%d{HH:mm}|%d{UNIX_MILLIS}|%msg%n</pattern>
</encoder>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>${RL:-${GENESIS_HOME}/runtime/logs/currentRun}/${PROCESS_NAME}_%d{yyyy-MM-dd}-1.log.request.gz</fileNamePattern>
</rollingPolicy>
</appender>
<logger name="global.genesis." level="info" additivity="false">
<appender-ref ref="RollingFile"/>
</logger>
<logger name="org.apache.commons.configuration2" level="info" additivity="false">
<appender-ref ref="RollingFile"/>
</logger>
<logger name="org.ehcache" level="info" additivity="false">
<appender-ref ref="RollingFile"/>
</logger>
<logger name="global.genesis.metrics" level="debug" additivity="false">
<appender-ref ref="MetricsRollingFile"/>
</logger>
<logger name="global.genesis.net.logging.RequestLogger" level="trace" additivity="false">
<appender-ref ref="RequestLogRollingFile"/>
</logger>
<root level="info">
<appender-ref ref="RollingFile"/>
</root>
</configuration>
Choosing a logging backend
A Genesis process logs through log4j2 unless you choose Logback. You make the choice when you build your application: the Genesis exec plugin puts exactly one logging backend on your application's runtime classpath. To use Logback, set this Gradle property in your application's server/gradle.properties:
genesis.logging-backend=logback
The accepted values are log4j (the default) and logback, in any case. Any other value fails the build. You can also set the backend in the logging block of the genesisExec extension:
genesisExec {
logging {
backend.set(LOGBACK)
}
}
The constants this block accepts are LOG4J and LOGBACK. log4j2 is the default, so to go back to it you don't need to set anything: remove the Logback setting, whether it is the Gradle property or the backend.set(LOGBACK) line.
If you set both, the value in the genesisExec block wins; the Gradle property is only its default.
The change takes effect only once your application's process classpath is rebuilt. After you change the backend, run genesisSync (or rebuild and run genesisInstall), then restart the processes.
- At start-up, a process uses the logging backend it finds on its classpath. The
LogFrameworksystem definition item no longer selects one. - The
LogFrameworkConfigsystem definition item names the configuration file. Its default islog4j2-default.xml. If Logback is the backend and the item still has that default, Genesis loadslogback-default.xmlinstead; both files ship with Genesis. Any other value is used as given, so if you name your own file, make sure it is written for the backend you chose. - To confirm which backend and configuration file a process is using, look for the
INFOline that each process logs at start-up, for exampleLogging backend: Logback (config: <path>). The backend isLog4j2orLogback, and the config is the absolute path of the file that was loaded. If Genesis can't find the file in its configuration folders, the line shows only the file name, such aslogback-default.xml, instead of a path. - If more than one backend is on the classpath, the process prints
Too many logging controllers; unable to initialize logging services; found ...to standard error, then carries on with whichever backend it found first. Check that your dependencies don't add a second backend. - The setting also changes the test runtime classpath of the module that applies the Genesis exec plugin: with Logback, its tests log through Logback instead of log4j2.
Log directories
Genesis utilizes three key environment variables to define log directory locations:
$L(Log Directory):
- Purpose: The main directory for current log files. This is where Genesis writes logs during its active operation.
- Default:
${GENESIS_HOME}/runtime/logs - Used By:
log4j2-default.xmlandlogback-default.xmlfor current log output.
$RL(Rolling Log Directory):
- Purpose: Stores rolling logs. Log files are often "rolled over" (archived and replaced with new ones) based on size or time to prevent them from becoming too large. This directory also holds logs moved during the
startProcesscommand execution. - Default:
${L}/currentRun(a subdirectory within the main log directory$L) - Used By:
log4j2-default.xmlandlogback-default.xmlfor rolling log configurations and thestartProcesscommand.
$AL(Archive Log Directory):
- Purpose: Stores archived logs, typically older logs moved during server startup processes, for long-term storage.
- Default:
${L}/archive(another subdirectory within the main log directory$L) - Used By: The
startServercommand for archiving previous logs.
Configuration
- Automatic Setup: These environment variables (
$L,$RL,$AL) are automatically configured with their default values when you source the setup script located at$GENESIS_HOME/genesis/util/setup.sh. - Customization: If you need to use different locations for your logs, you can define
$L,$RL, or$ALas environment variables before sourcing thesetup.shscript. Your custom values will then take precedence over the defaults.
For more details on how the $RL and $AL directories are used in practice, refer to the documentation for the startServer and startProcess commands.
Redirecting Standard Output and Error
By default, messages sent to standard output (stdout) and standard error (stderr) by Genesis processes are not captured in the log files. This standard output is ignored by default and standard error is written to a log.err file in the $L directory.
If you want to capture all output, including stdout and stderr, directly within the process's log files, you can change this behavior by setting the genesis system definiiton property RedirectStreamsToLog to true.
Setting this property to true ensures that standard output and error messages are written to the same process log files, providing a consolidated view of all process output that will be managed the same way as other log messages.
Logging level
The default logging level for processes is set in the processes xml definition file.
The loggingLevel can also be changed dynamically on a running process using the LogLevel command
Logging context
Additional contextual attributes can be added to log statements. If enabled, the context is added on inbound requests/messages and propagated through the system.
Genesis makes use of slf4j's MDC to add this contextual information.
Context attributes
The following Genesis-specific attributes are added to the logging context:
- Message Type
- Source Ref
- Username (if present)
- Payload
Example
The below shows example values for the Genesis-specific attributes listed previously.
| Attribute | Value |
|---|---|
| genesis.message_type | EVENT_TRADE_INSERT |
| genesis.source_ref | 6045bdfffe1177d3-00005df4-00000004-1f1e5fe74723987e-c672dc68:1 |
| genesis.username | JohnDoe |
| genesis.payload | {"MESSAGE_TYPE":"EVENT_TRADE_INSERT","USER_NAME":"JohnDoe","SESSION_AUTH_TOKEN":"********","REFRESH_AUTH_TOKEN":null,"VALIDATE":false,"IGNORE_WARNINGS":true,"DETAILS":}"INSTRUMENT_ID":"VOD","COUNTERPARTY_ID":"GENESIS","QUANTITY":10,"PRICE":1.5,"SIDE":"BUY"},"SOURCE_REF":"1"} |
Set-up
To enable Genesis attributes to be added to the logging context, set the LoggingContextEnabled system definition property to true. This property defaults to false.
item(name = "LoggingContextEnabled", value = "true")
You can then configure your logging configuration file as normal to show MDC attributes.
If Tracing is enabled, then additional tracing information is also available in MDC, see here for more details.
Example log4j2 configuration
Show all MDC attributes:
<Pattern>%d{dd MMM yyyy HH:mm:ss.SSS} %-4relative [%t] %-5level %logger{35} [%X] - %m%n</Pattern>
Show just the Source Ref attribute:
<Pattern>%d{dd MMM yyyy HH:mm:ss.SSS} %-4relative [%t] %-5level %logger{35} [SourceRef = %X{genesis.source_ref}] - %m%n</Pattern>
Show all MDC attributes in json format:
<JsonLayout complete="false" compact="true" eventEol="true" properties="true" />
Show just the Source Ref attribute in json format:
<JsonLayout complete="false" compact="true" eventEol="true" >
<KeyValuePair key="SourceRef" value="${ctx:genesis.source_ref}"/>
</JsonLayout>
Example Logback configuration
Show just the Source Ref attribute. This is the Logback equivalent of the log4j2 <Pattern> above:
<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
<pattern>%d{dd MMM yyyy HH:mm:ss.SSS} %-4relative [%thread] %-5level %logger{35} [SourceRef = %X{genesis.source_ref}] - %msg%n</pattern>
</encoder>