1.3  Configuring Logging

1.3.1 Logging Introduction

Logging in MWS is handled by the Logback logging framework and is configured in the /opt/mws/etc/logback.groovy file.

We highly recommend that you leave the JodaTimeConverter import and conversionRule in the logback.groovy file as originally included. This converter provides improved performance and support for the specification of time and date for Adaptive Computing's 'Standard Log Format' in the log files.

The example below shows a minimal logging configuration that logs standard MWS messages to /opt/mws/log/mws.log and exception stack traces to /opt/mws/log/stacktrace.log. Note that this example is not configured to log events or auditing, which are described in subsequent subsections.

appender("ROOTLOG", RollingFileAppender) {
    file = '/opt/mws/log/mws.log'
    rollingPolicy(FixedWindowRollingPolicy) {
        fileNamePattern = "/opt/mws/log/mws.log.%i"
        maxIndex = 10 // Retain only the 10 most recent log files, delete older logs to save space
    }
    triggeringPolicy(SizeBasedTriggeringPolicy) {
        maxFileSize = '100MB' // The maximum file size for a single log file
    }
    encoder(PatternLayoutEncoder) {
        pattern = "%j\t%t\t%p\t%c\t0\t\t%m%n" // Configures the output format of each log entry
    }
}

appender("STACKTRACE", RollingFileAppender) {
    file = '/opt/mws/log/stacktrace.log'
    encoder(PatternLayoutEncoder) {
        pattern = "%m%n"
    }
    rollingPolicy(FixedWindowRollingPolicy) {
        fileNamePattern = "/opt/mws/log/stacktrace.log.%i"
    }
    triggeringPolicy(SizeBasedTriggeringPolicy) {
        maxFileSize = '100MB'
    }
}

root(ERROR, ['ROOTLOG']) // NOTE: This definition is a catch-all for any logger not defined below

Alternatively, you can configure a console appender instead of a rolling file, as shown below:

…
appender('ROOTLOG', ConsoleAppender) {
    encoder(PatternLayoutEncoder) {
         pattern = "%j\t%t\t%p\t%c\t0\t\t%m%n" // Configures the output format of each log entry
    }
}
…

1.3.2 Configuring an Event Log

Logging events to a separate log file requires that you make a few changes to the configuration in the /opt/mws/etc/logback.groovy file so that events will be logged to the events.log file, and all other MWS logging information will be sent to the mws.log file.

Causing events.log to Roll Based on a Time Window

You can specify how often the events.log file rolls. The following example illustrates the configuration changes you will need to make to /opt/mws/etc/mws-config.groovy to cause the events.log file to roll based on a time window.

Note the following three examples:

• In this example, /opt/mws/etc/mws-config.groovy is configured so that events.log rolls daily at midnight:

Daily rolling events.log configuration in mws-config.groovy
------------------------------------
appender("EVENTS", RollingFileAppender) {
    file = '/opt/mws/log/events.log'
    encoder(PatternLayoutEncoder) {
        pattern = "%m%n"
    }
    rollingPolicy(TimeBasedRollingPolicy) {
        fileNamePattern = '/opt/mws/log/events.%d{yyyy-MM-dd}'
    }
}
// Logs event information to the events log, not the rootLog
logger("com.ace.mws.events.EventFlatFileWriter", DEBUG, ["EVENTS"], false)

Note the RollingFileAppender and the TimeBasedRollingPolicy lines. These lines configure MWS to write the event log to the events.log file. Rolled log files will have a date appended to their name in this format: 'yyyy-MM-dd' (for example, events.log.2025-02-28).

• If you want the event log file to roll at the beginning of each month, change the fileNamePattern TimeBasedRollingPolicy date format to yyyy-MM. For example:

Monthly event logs
------------------------------------
appender("EVENTS", RollingFileAppender) {
    file = '/opt/mws/log/events.log'
    encoder(PatternLayoutEncoder) {
        pattern = "%m%n"
    }
    rollingPolicy(TimeBasedRollingPolicy) {
        fileNamePattern = '/opt/mws/log/events.%d{yyyy-MM}'
    }
}
// Logs event information to the events log, not the rootLog
logger("com.ace.mws.events.EventFlatFileWriter", DEBUG, ["EVENTS"], false)

• If you want the event log file to roll at the beginning of each hour, change the date format to yyyy-MM-dd_HH:00, for example:

Hourly event logs
------------------------------------
appender("EVENTS", RollingFileAppender) {
    file = '/opt/mws/log/events.log'
    encoder(PatternLayoutEncoder) {
        pattern = "%m%n"
    }
    rollingPolicy(TimeBasedRollingPolicy) {
        fileNamePattern = '/opt/mws/log/events.%d{yyyy-MM-dd_HH:00}'
    }
}
// Logs event information to the events log, not the rootLog
logger("com.ace.mws.events.EventFlatFileWriter", DEBUG, ["EVENTS"], false)

Configuring events.log to Roll Based on a File Size Threshold

You can also configure the events.log file to roll when the log size exceeds a specified threshold. The following example illustrates the configuration changes you will need to make to /opt/mws/etc/logback.groovy to cause the events.log file to roll on a size threshold. (In this example, /opt/mws/etc/logback.groovy is configured so that events.log rolls when its size exceeds 50 MB).

logback.groovy configuration that rolls events.log based on file size
------------------------------------
appender("EVENTS", RollingFileAppender) {
    file = '/opt/mws/log/events.log'
    encoder(PatternLayoutEncoder) {
        pattern = "%m%n"
    }
    rollingPolicy(FixedWindowRollingPolicy) {
        fileNamePattern = "/opt/mws/log/stacktrace.log.%i"
        maxIndex = 10
    }
    triggeringPolicy(SizeBasedTriggeringPolicy) {
        maxFileSize = '50MB'
    }
}
// Logs event information to the events log, not the rootLog
logger("com.ace.mws.events.EventFlatFileWriter", DEBUG, ["EVENTS"], false)

Note that maxFileSize is set to '50MB.' This means that when the events.log file exceeds 50 MB, it will roll.

The name for the rolled log will be 'events.log.1'. When the new events.log file exceeds 50 MB, it will roll and be named 'events.log.1', while the old 'events.log.1' file will be renamed 'events.log.2'. This process will continue until the optional maxBackupIndex value is met. In the example above, maxIndex is set to 10. This means that MWS will delete all except the ten most recent events.log files. Using this feature helps prevent hard drives from filling up.

Deleting Old Events

MWS will automatically delete events older than 30 days (by default). For more information, including how to change this default, see mws.events.expireAfterSeconds in 8.2  MWS Configuration.

1.3.3 Configuring an Audit Trail Log

Audit logging enables you to track changes to Permissions, Roles, and Principals:

logback.groovy configuration that enables audit logging
------------------------------------
appender("AUDIT", RollingFileAppender) {
    file = '/opt/mws/log/audit.log'
    encoder(PatternLayoutEncoder) {
        pattern = "%j\t\t\t%c{1}\t\t\t%m%n"
    }
    rollingPolicy(TimeBasedRollingPolicy) {
        fileNamePattern = '/opt/mws/log/audit.%d{yyyy-MM-dd}'
    }
}
// Logs audit information to the audit log, not the rootLog
logger("mws.audit", DEBUG, ["AUDIT"], false)

You can customize audit logging in ways you can customize event logging. For example, you can specify how often the audit.log file rolls. You can also configure the audit.log file to roll when the log size exceeds a specified threshold.

Follow the same steps indicated in the previous section on Configuring an Event Log for instruction on customizing audit logging; customization processes are the same for audit logging as for events logging.

audit.log File Format

The default location to which the audit trail log is written is /opt/mws/log/audit.log. The log format is yyyy-MM-dd HH:mm:ss resource username action data. The following table offers a description for attributes included in the log format:

Sample audit.log format:

Audit trail log format
------------------------------------

2024-10-30 14:39:32,120 PRINCIPAL 'admin' updated resource named 'Engineering2' with values: 
     "name": "Engineering3",
     "attachedPrincipals": [{"name": "Engineering"}]