Logging

Owned by ScottS
Last updated: Jun 07, 2016 by Misagh Moayyed

New CAS documentation site

CAS documentation has moved over to apereo.github.io/cas, starting with CAS version 4.x. The wiki will no longer be maintained. For the most recent version of the documentation, please refer to the aforementioned link.

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 Commons Logging framework as a facade for the log4j engine by default. The default log4j engine can be replaced by any supported by Commons Logging if needed.

log4j Configuration

This section assumes you are using the default log4j engine.

The log4j configuration file is located in ${project.home}/cas-server-webapp/src/main/webapp/WEB-INF/classes/log4j.properties. At deployment time it is located at $CATALINA_HOME/webapps/cas/WEB-INF/classes/log4j.properties. By default logging is set to INFO for ja-sig code and WARN for Spring code. While debugging you may want to set those to DEBUG. When in production though, you probably want to run them both as WARN. Depending on your needs, it may make sense to keep the defaults (INFO and WARN).

In the default configuration, CAS logs to a log4j FileAppender in the current working directory of the java process. If you start/stop your servlet container from a shell, it's very likely the cas.log file will move around depending on the current directory where you start the container, e.g. catalina.sh start for Tomcat. It's strongly recommended that you change the file appender path to an absolute path suitable for your environment such as /var/log/cas.log. A good choice for Tomcat is something like ${catalina.home}/logs/cas.log.

The following is an example of a real-world log4j.properties file used in production at Virginia Tech for CAS server version 3.3.3.

Version-Specific Warning

As of CAS Server 3.4, an XML-based log4j configuration file is used instead of a properties file.

Real-World log4j.properties File
log4j.rootLogger=ERROR, stdout, logfile

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d %p [%c] - <%m>%n

log4j.appender.logfile=org.apache.log4j.DailyRollingFileAppender
log4j.appender.logfile.File=/apps/local/cas/logs/cas.log
log4j.appender.logfile.DatePattern='.'yyyy-MM-dd
log4j.appender.logfile.Append=true
log4j.appender.logfile.layout=org.apache.log4j.PatternLayout
log4j.appender.logfile.layout.ConversionPattern=%d %-5p [%c] - %m%n

# WARNING: Setting the org.springframework logger to DEBUG displays debug information about
# the request parameter values being bound to the command objects.  This could expose your
# password in the log file.  If you are sharing your log files, it is recommend you selectively
# apply DEBUG level logging on a an org.springframework.* package level (i.e. org.springframework.dao)
log4j.logger.org.springframework=INFO
#log4j.logger.org.springframework.web.servlet.i18n=DEBUG
#log4j.logger.org.springframework.web.servlet.view=DEBUG
#log4j.logger.org.quartz=DEBUG

log4j.logger.org.jasig=INFO
# WARNING: Setting the flow package to DEBUG will display
# the parameters posted to the login servlet including
# cleartext authentication credentials
log4j.logger.org.jasig.cas.web.flow=INFO
log4j.logger.org.jasig.cas.authentication=INFO
log4j.logger.org.jasig.cas.web.flow.TicketGrantingTicketCheckAction=INFO
log4j.logger.org.jasig.cas.services.DefaultServiceRegistry=INFO
log4j.logger.org.jasig.cas.services=INFO

# Ignore verbose Person Directory warning messages about
# character encoding when loading LDAP attributes
log4j.logger.org.jasig.services.persondir.support.ldap.PersonAttributesMapper=ERROR

log4j.logger.edu.vt.middleware.cas=INFO
#log4j.logger.com.mchange=DEBUG
#log4j.logger.org.inspektr=DEBUG

The following log4j.xml configuration file is used in production at Virginia Tech for CAS 3.4.4.

Example CAS 3.4.x log4j Configuration
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration debug="false" xmlns:log4j="http://jakarta.apache.org/log4j/">
 
  <!-- CAS application log -->
  <appender name="cas" class="org.apache.log4j.DailyRollingFileAppender">
    <param name="File" value="/apps/local/cas/logs/cas.log" />
    <param name="Append" value="true" />
    <param name="DatePattern" value="'.'yyyy-MM-dd" />
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d %p [%c] - %m%n"/>
    </layout>
  </appender>

  <!-- For JPA diagnostics -->
  <appender name="jpa" class="org.apache.log4j.DailyRollingFileAppender">
    <param name="File" value="/apps/local/cas/logs/jpa.log" />
    <param name="Append" value="true" />
    <param name="DatePattern" value="'.'yyyy-MM-dd" />
    <layout class="org.apache.log4j.EnhancedPatternLayout">
      <param name="ConversionPattern" value="%d %p [%c] - %m%n%throwable{10}"/>
    </layout>
  </appender>

  <!-- Perf4J appenders -->
  <appender name="perf4j" class="org.apache.log4j.DailyRollingFileAppender">
    <param name="File" value="/apps/local/cas/logs/perf4j.log"/>
    <param name="Append" value="true" />
    <param name="DatePattern" value="'.'yyyy-MM-dd" />
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%m%n"/>
    </layout>
  </appender>

  <!--
     This AsyncCoalescingStatisticsAppender groups StopWatch log messages
     into GroupedTimingStatistics messages which it sends on the
     file appender defined below
  -->
  <appender name="coalesce" class="org.perf4j.log4j.AsyncCoalescingStatisticsAppender">
    <param name="TimeSlice" value="300000"/>
    <appender-ref ref="perf4j"/>
    <appender-ref ref="perf4jGraphMean"/>
    <appender-ref ref="perf4jGraphTPS"/>
  </appender>

  <appender name="perf4jGraphMean" class="org.perf4j.log4j.GraphingStatisticsAppender">
    <!-- Possible GraphTypes are Mean, Min, Max, StdDev, Count and TPS -->
    <param name="GraphType" value="Mean"/>
    <!-- The tags of the timed execution blocks to graph are specified here -->
    <param name="TagNamesToGraph" value="DESTROY_TICKET_GRANTING_TICKET,GRANT_SERVICE_TICKET,GRANT_PROXY_GRANTING_TICKET,VALIDATE_SERVICE_TICKET,CREATE_TICKET_GRANTING_TICKET" />
  </appender>

  <appender name="perf4jGraphTPS" class="org.perf4j.log4j.GraphingStatisticsAppender">
    <param name="GraphType" value="TPS" />
    <param name="TagNamesToGraph" value="DESTROY_TICKET_GRANTING_TICKET,GRANT_SERVICE_TICKET,GRANT_PROXY_GRANTING_TICKET,VALIDATE_SERVICE_TICKET,CREATE_TICKET_GRANTING_TICKET" />
  </appender>

  <!-- Loggers -->
  <!--
    The Perf4J logger. Note that org.perf4j.TimingLogger is the value of the
    org.perf4j.StopWatch.DEFAULT_LOGGER_NAME constant. Also, note that
    additivity is set to false, which is usually what is desired - this means
    that timing statements will only be sent to this logger and NOT to
    upstream loggers.
  -->
  <logger name="org.perf4j.TimingLogger" additivity="false">
    <level value="INFO"/>
    <appender-ref ref="coalesce"/>
  </logger>

  <!--
    WARNING: Setting the org.springframework logger to DEBUG displays debug information about
    the request parameter values being bound to the command objects.  This could expose your
    password in the log file.  If you are sharing your log files, it is recommend you selectively
    apply DEBUG level logging on a an org.springframework.* package level (i.e. org.springframework.dao)
  -->
  <logger name="org.springframework">
    <level value="INFO" />
  </logger>

  <logger name="org.springframework.webflow">
    <level value="INFO" />
  </logger>

  <logger name="org.jasig.cas">
    <level value="INFO" />
  </logger>

  <logger name="org.jasig.cas.ticket.registry">
    <level value="INFO" />
  </logger>

  <logger name="org.jasig.cas.authentication">
    <level value="INFO" />
  </logger>

  <logger name="org.jasig.cas.util.HttpClient">
    <level value="INFO" />
  </logger>

  <logger name="org.jasig.cas.web.support">
    <level value="INFO" />
  </logger>

  <logger name="org.jasig.cas.web.ServiceValidateController">
    <level value="INFO" />
  </logger>

  <!-- Troubleshoot JPA ticket registry problems at TRACE -->
  <logger name="org.jasig.cas.ticket.registry.JpaTicketRegistry"
    additivity="false">
    <level value="INFO" />
    <appender-ref ref="jpa"/>
  </logger>

  <!--
    WARNING: Setting the flow package to DEBUG will display
    the parameters posted to the login servlet including
    cleartext authentication credentials
  -->
  <logger name="org.jasig.cas.web.flow">
    <level value="INFO" />
  </logger>

  <logger name="edu.vt.middleware.cas">
    <level value="INFO" />
  </logger>

  <logger name="edu.vt.middleware.cas.authentication.principal">
    <level value="INFO" />
  </logger>

  <logger name="org.jasig.services.persondir">
    <level value="DEBUG" />
  </logger>

  <!-- Troubleshoot database connection pooling problems in TRACE -->
  <logger name="com.mchange.v2">
    <level value="WARN" />
  </logger>

  <!-- Troubleshoot LDAP connection pool problems in DEBUG -->
  <logger name="org.springframework.ldap.pool">
    <level value="INFO" />
  </logger>

  <!--
    The root logger sends all log statements EXCEPT those sent to the perf4j
    logger to System.out.
  -->
  <root>
    <level value="ERROR"/>
    <appender-ref ref="cas"/>
  </root>
</log4j:configuration>