Logging

CAS provides a logging facility that logs important informational events like authentication success and failure; it can be customized to produce additional information for troubleshooting. CAS uses the Slf4j Logging framework as a facade for the Log4j engine by default.

The default log4j configuration file is located in src/main/resources/log4j2.xml of the cas-server-webapp-resources source module. In the cas.war it is found at the root of the cas-server-webapp-resources*.jar. The cas-overlay comes with an external log42.xml in etc/cas/config and a property logging.config=file:/etc/cas/config/log4j2.xml set to reference it. By default logging is set to INFO for all functionality related to org.apereo.cas code. For debugging and diagnostic purposes you may want to set these levels to DEBUG or TRACE.

Production

You should always run everything under WARN. In production warnings and errors are things you care about. Everything else is just diagnostics. Only turn up DEBUG or INFO if you need to research a particular issue.

CAS Custom Log4j2 plugins

The log4j2.xml file use by CAS includes custom Log4j2 plugins:

  • CasAppender: The CasAppender wraps another regular appender and removes sensitive values from the log entries such as Ticket Granting Tickets or Proxy Granting Tickets.

  • ExceptionOnlyFilter: In order to allow CAS to freely log unexpected errors at WARN and ERROR without obscuring everything with stacktraces, exceptions in the logs are disabled by default but there are log4j2.xml properties that can turn them back on. By default, all exceptions are written to a dedicated stacktrace rolling log file and this is done using a custom ExceptionOnlyFilter nested in the CasAppender.

Log4j2 Properties

The log4j2.xml file includes properties for various settings and those can be set in the properties section of the log4j2.xml file, in a property file called log4j2.component.properties on the classpath, or as system properties. If setting properties in a log4j2.component.properties, be sure to include:

1

Log4jContextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector

in order to keep using asynchronous logging which CAS sets by default. To turn off asynchronous logging, include the following in log4j2.component.properites or as a system property:

1

Log4jContextSelector=org.apache.logging.log4j.core.selector.BasicContextSelector

Configuration

It is often helpful to externalize the log4j2.xml file to a system path to preserve settings between upgrades. The location of log4j2.xml file by default is on the runtime classpath and can be controlled via the CAS properties.

The following settings and properties are available from the CAS configuration catalog:

The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.logging.mdc-enabled=true

    • Allow CAS to add http request details into the logging's MDC filter. Mapped Diagnostic Context is essentially a map maintained by the logging framework where the application code provides key-value pairs which can then be inserted by the logging framework in log messages. MDC data can also be highly helpful in filtering messages or triggering certain actions.

    The configuration settings listed below are tagged as Third Party in the CAS configuration metadata. This flag indicates that the configuration setting is not controlled, owned or managed by the CAS ecosystem, and affects functionality that is offered by a third-party library, such as Spring Boot or Spring Cloud to CAS. For additional info, you might have to visit the third-party source to find more details.

  • logging.charset.console=

    • Charset to use for console output.

  • logging.charset.file=

    • Charset to use for file output.

  • logging.config=

    • Location of the logging configuration file. For instance, `classpath:logback.xml` for Logback.

  • logging.exception-conversion-word=%wEx

    • Conversion word used when logging exceptions.

  • logging.file=

    • Log file name (for instance, `myapp.log`). Names can be an exact location or relative to the current directory.

    Deprecation status is ERROR with a replacement setting: logging.file.name.
  • logging.file.clean-history-on-start=false

    • Whether to clean the archive log files on startup. Only supported with the default logback setup.

    Deprecation status is WARNING with a replacement setting: logging.logback.rollingpolicy.clean-history-on-start.
  • logging.file.max-history=7

    • Maximum number of days archive log files are kept. Only supported with the default logback setup.

    Deprecation status is WARNING with a replacement setting: logging.logback.rollingpolicy.max-history.
  • logging.file.max-size=10MB

    • Maximum log file size. Only supported with the default logback setup.

    Deprecation status is WARNING with a replacement setting: logging.logback.rollingpolicy.max-file-size.
  • logging.file.name=

    • Log file name (for instance, `myapp.log`). Names can be an exact location or relative to the current directory.

  • logging.file.path=

    • Location of the log file. For instance, `/var/log`.

  • logging.file.total-size-cap=0B

    • Total size of log backups to be kept. Only supported with the default logback setup.

    Deprecation status is WARNING with a replacement setting: logging.logback.rollingpolicy.total-size-cap.
  • logging.group=

    • Log groups to quickly change multiple loggers at the same time. For instance, `logging.group.db=org.hibernate,org.springframework.jdbc`.

  • logging.level=

    • Log levels severity mapping. For instance, `logging.level.org.springframework=DEBUG`.

  • logging.logback.rollingpolicy.clean-history-on-start=false

    • Whether to clean the archive log files on startup.

  • logging.logback.rollingpolicy.file-name-pattern=${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz

    • Pattern for rolled-over log file names.

  • logging.logback.rollingpolicy.max-file-size=10MB

    • Maximum log file size.

  • logging.logback.rollingpolicy.max-history=7

    • Maximum number of days archive log files are kept.

  • logging.logback.rollingpolicy.total-size-cap=0B

    • Total size of log backups to be kept.

  • logging.path=

    • Location of the log file. For instance, `/var/log`.

    Deprecation status is ERROR with a replacement setting: logging.file.path.
  • logging.pattern.console=%clr(%d{${LOG_DATEFORMAT_PATTERN:-yyyy-MM-dd HH:mm:ss.SSS}}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}

    • Appender pattern for output to the console. Supported only with the default Logback setup.

  • logging.pattern.dateformat=yyyy-MM-dd HH:mm:ss.SSS

    • Appender pattern for log date format. Supported only with the default Logback setup.

  • logging.pattern.file=%d{${LOG_DATEFORMAT_PATTERN:-yyyy-MM-dd HH:mm:ss.SSS}} ${LOG_LEVEL_PATTERN:-%5p} ${PID:- } --- [%t] %-40.40logger{39} : %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}

    • Appender pattern for output to a file. Supported only with the default Logback setup.

  • logging.pattern.level=%5p

    • Appender pattern for log level. Supported only with the default Logback setup.

  • logging.pattern.rolling-file-name=${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz

    • Pattern for rolled-over log file names. Supported only with the default Logback setup.

    Deprecation status is WARNING with a replacement setting: logging.logback.rollingpolicy.file-name-pattern.
  • logging.register-shutdown-hook=false

    • Register a shutdown hook for the logging system when it is initialized.