Logback samples

This page provides example Logback configuration files for customizing your ADS logging. The Logback logging system is used by Spring Boot. For details on how ADS uses Logback, see Audit logging.

note

The samples that route admin and eval events include two logger namespaces:

• com.axiomatics.audit.ads.*: ADS audit loggers for standard authorization decisions.
• com.axiomatics.audit.arq.raw.*: CAQ audit loggers for reverse query events. These loggers are only active when ADS runs in ads_caq mode.

• Admin events
• Eval events
• Both events to one single file
• Both events to two separate files
• JSON format to console

To enable audit events and log only administrative events:

logbackAdmin.xml

<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>
    <property name="ADMIN_LOG_FILE" value="./logs/ads-admin-event.log"/>
    <appender name="ADMIN_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
            <providers>
                <timestamp><fieldName>timestamp</fieldName></timestamp>
                <version/>
                <loggerName/>
                <threadName/>
                <logLevel/>
                <stackTrace/>
                <mdc/>
                <!-- custom provider -->
                <provider class="com.axiomatics.ads.util.CustomRawMessageJsonProvider">
                    <fieldName>message</fieldName>
                </provider>
            </providers>
        </encoder>
        <file>${ADMIN_LOG_FILE}</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN:-${ADMIN_LOG_FILE}.%d{yyyy-MM-dd}.%i.log.gz}</fileNamePattern>
            <cleanHistoryOnStart>${LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START:-false}</cleanHistoryOnStart>
            <maxFileSize>${LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE:-10MB}</maxFileSize>
            <totalSizeCap>${LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP:-0}</totalSizeCap>
            <maxHistory>${LOGBACK_ROLLINGPOLICY_MAX_HISTORY:-7}</maxHistory>
        </rollingPolicy>
    </appender>
    <root>
        <appender-ref ref="CONSOLE"/>
    </root>
    <!-- ADS: standard authorization decision audit events -->
    <logger name="com.axiomatics.audit.ads.admin" additivity="true">
        <appender-ref ref="ADMIN_FILE"/>
    </logger>
    <!-- CAQ: reverse query audit events (ads_caq mode only) -->
    <logger name="com.axiomatics.audit.arq.raw.admin" additivity="true">
        <appender-ref ref="ADMIN_FILE"/>
    </logger>
</configuration>

To enable audit events and log only evaluation events:

logbackEval.xml

<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>
    <property name="EVAL_LOG_FILE" value="./logs/ads-eval-event.log"/>
    <appender name="EVAL_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
            <providers>
                <timestamp><fieldName>timestamp</fieldName></timestamp>
                <version/>
                <loggerName/>
                <threadName/>
                <logLevel/>
                <stackTrace/>
                <mdc/>
                <!-- custom provider -->
                <provider class="com.axiomatics.ads.util.CustomRawMessageJsonProvider">
                    <fieldName>message</fieldName>
                </provider>
            </providers>
        </encoder>
        <file>${EVAL_LOG_FILE}</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN:-${EVAL_LOG_FILE}.%d{yyyy-MM-dd}.%i.log.gz}</fileNamePattern>
            <cleanHistoryOnStart>${LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START:-false}</cleanHistoryOnStart>
            <maxFileSize>${LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE:-10MB}</maxFileSize>
            <totalSizeCap>${LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP:-0}</totalSizeCap>
            <maxHistory>${LOGBACK_ROLLINGPOLICY_MAX_HISTORY:-7}</maxHistory>
        </rollingPolicy>
    </appender>
    <root>
        <appender-ref ref="CONSOLE"/>
    </root>
    <!-- ADS: standard authorization decision audit events -->
    <logger name="com.axiomatics.audit.ads.eval" additivity="true">
        <appender-ref ref="EVAL_FILE"/>
    </logger>
    <!-- CAQ: reverse query audit events (ads_caq mode only) -->
    <logger name="com.axiomatics.audit.arq.raw.eval" additivity="true">
        <appender-ref ref="EVAL_FILE"/>
    </logger>
</configuration>

To enable audit events and log both administrative and evaluation events into one file:

logbackBothAdminEval.xml

<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>
    <property name="AUDIT_LOG_FILE" value="./logs/ads-audit.log"/>
    <appender name="AUDIT_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
            <providers>
                <timestamp><fieldName>timestamp</fieldName></timestamp>
                <version/>
                <loggerName/>
                <threadName/>
                <logLevel/>
                <stackTrace/>
                <mdc/>
                <!-- custom provider -->
                <provider class="com.axiomatics.ads.util.CustomRawMessageJsonProvider">
                    <fieldName>message</fieldName>
                </provider>
            </providers>
        </encoder>
        <file>${AUDIT_LOG_FILE}</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN:-${AUDIT_LOG_FILE}.%d{yyyy-MM-dd}.%i.log.gz}</fileNamePattern>
            <cleanHistoryOnStart>${LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START:-false}</cleanHistoryOnStart>
            <maxFileSize>${LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE:-10MB}</maxFileSize>
            <totalSizeCap>${LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP:-0}</totalSizeCap>
            <maxHistory>${LOGBACK_ROLLINGPOLICY_MAX_HISTORY:-7}</maxHistory>
        </rollingPolicy>
    </appender>
    <root>
        <appender-ref ref="CONSOLE"/>
    </root>
    <logger name="com.axiomatics.audit" additivity="true">
        <appender-ref ref="AUDIT_FILE"/>
    </logger>
</configuration>

To enable audit events and log both administrative and evaluation events into separate files:

logbackSeparateAdminEval.xml

<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>
    <property name="ADMIN_LOG_FILE" value="./logs/ads-admin-event.log"/>
    <property name="EVAL_LOG_FILE" value="./logs/ads-eval-event.log"/>
    <appender name="ADMIN_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
            <providers>
                <timestamp><fieldName>timestamp</fieldName></timestamp>
                <version/>
                <loggerName/>
                <threadName/>
                <logLevel/>
                <stackTrace/>
                <mdc/>
                <!-- custom provider -->
                <provider class="com.axiomatics.ads.util.CustomRawMessageJsonProvider">
                    <fieldName>message</fieldName>
                </provider>
            </providers>
        </encoder>
        <file>${ADMIN_LOG_FILE}</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN:-${ADMIN_LOG_FILE}.%d{yyyy-MM-dd}.%i.log.gz}</fileNamePattern>
            <cleanHistoryOnStart>${LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START:-false}</cleanHistoryOnStart>
            <maxFileSize>${LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE:-10MB}</maxFileSize>
            <totalSizeCap>${LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP:-0}</totalSizeCap>
            <maxHistory>${LOGBACK_ROLLINGPOLICY_MAX_HISTORY:-7}</maxHistory>
        </rollingPolicy>
    </appender>
    <appender name="EVAL_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
            <providers>
                <timestamp><fieldName>timestamp</fieldName></timestamp>
                <version/>
                <loggerName/>
                <threadName/>
                <logLevel/>
                <stackTrace/>
                <mdc/>
                <!-- custom provider -->
                <provider class="com.axiomatics.ads.util.CustomRawMessageJsonProvider">
                    <fieldName>message</fieldName>
                </provider>
            </providers>
        </encoder>
        <file>${EVAL_LOG_FILE}</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN:-${EVAL_LOG_FILE}.%d{yyyy-MM-dd}.%i.log.gz}</fileNamePattern>
            <cleanHistoryOnStart>${LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START:-false}</cleanHistoryOnStart>
            <maxFileSize>${LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE:-10MB}</maxFileSize>
            <totalSizeCap>${LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP:-0}</totalSizeCap>
            <maxHistory>${LOGBACK_ROLLINGPOLICY_MAX_HISTORY:-7}</maxHistory>
        </rollingPolicy>
    </appender>
    <root>
        <appender-ref ref="CONSOLE"/>
    </root>
    <!-- ADS: standard authorization decision audit events -->
    <logger name="com.axiomatics.audit.ads.admin" additivity="true">
        <appender-ref ref="ADMIN_FILE"/>
    </logger>
    <!-- CAQ: reverse query audit events (ads_caq mode only) -->
    <logger name="com.axiomatics.audit.arq.raw.admin" additivity="true">
        <appender-ref ref="ADMIN_FILE"/>
    </logger>
    <!-- ADS: standard authorization decision audit events -->
    <logger name="com.axiomatics.audit.ads.eval" additivity="true">
        <appender-ref ref="EVAL_FILE"/>
    </logger>
    <!-- CAQ: reverse query audit events (ads_caq mode only) -->
    <logger name="com.axiomatics.audit.arq.raw.eval" additivity="true">
        <appender-ref ref="EVAL_FILE"/>
    </logger>
</configuration>

To enable audit events and output all logs in JSON format to the console:

logbackJSON.xml

<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
            <providers>
                <timestamp><fieldName>timestamp</fieldName></timestamp>
                <version/>
                <loggerName/>
                <threadName/>
                <logLevel/>
                <stackTrace/>
                <mdc/>
                <!-- custom provider -->
                <provider class="com.axiomatics.ads.util.CustomRawMessageJsonProvider">
                    <fieldName>audit</fieldName>
                </provider>
            </providers>
        </encoder>
    </appender>
    <root>
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

note

The custom provider class is required for concise_json and verbose_json modes. If you generate logs in XML format, you can simplify Logback to use any standard mechanism and remove the custom provider.

Recommended config for custom providers

Include combinations of the following providers to ensure your logs are both structured and comprehensive:

• <timestamp/>: Adds the log event timestamp.

• <version/>: Specifies the log format version.

• <loggerName/>: Identifies the logger name.

• <threadName/>: Includes the thread name.

• <logLevel/>: Identifies the log level (INFO, ERROR, etc.).

• <mdc/>: Includes Mapped Diagnostic Context (MDC), such as OpenTelemetry trace details. For example:

  "trace_id":"1f6cdf5fe684ac866bf83967d9eef65c","trace_flags":"01","span_id":"5956c99996ef8825"

• <stackTrace/>: Appends the full stack trace when an exception occurs.

Logback and tracing information

If you enable tracing through OpenTelemetry or another agent, you can include tracing context such as span_id or trace_id in your logs. Add the <mdc/> field within the <providers> section as shown below:

<providers>
    <timestamp><fieldName>timestamp</fieldName></timestamp>
    <version/>
    <loggerName/>
    <threadName/>
    <logLevel/>
    <stackTrace/>
    <mdc>
        <includeMdcKeyName>trace_id</includeMdcKeyName>
    </mdc>
    ...
</providers>
...

tip

For full details on audit logging configuration in ADS, see Audit logging.