You are viewing the development documentation for the Apereo CAS server. The functionality presented here is not officially released yet. This is a work in progress and will be continually updated as development moves forward. To view the documentation for a specific Apereo CAS server release, please choose an appropriate version. The release schedule is also available here.
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
source module. In the
cas.war it is found at the root of the
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
For debugging and diagnostic purposes you may want to set these levels to
You should always run everything under
WARN. In production warnings and errors are things you care about. Everything else is just diagnostics. Only
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.xml file includes properties for various settings and those can be set in the properties section
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:
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:
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:
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.