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 is not strictly necessary in the end-user CAS configuration, because a default value may be assigned or the feature in question may not be immediately intended for use. You may want to own the setting and update it assigned value, assuming the intended feature controlled by the setting is utilized.

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.