WORKERS AHEAD!
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.
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
.
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:
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. |