Debug Logging

Perform these steps to temporarily capture debug messages until the next time AM or the container in which it runs is restarted:

1. Log in to the AM console as the root administrator, amAdmin.

   Important

   Only the amAdmin administrator account can access the Logback.jsp page and alter the debug settings; delegated administrators do not have access.

2. Navigate to Logback.jsp in the root context of the AM installation, for example https://openam.example.com:8443/openam/Logback.jsp.

   No links to this page are provided in the AM console.

3. Select the class to debug in the Logger column, or choose the global ROOT logger, and then click Edit.

   The page will resemble the following (truncated for easier viewing):

   

   1. If the class to debug is not in the table, select it in the Add logger field at the bottom of the page, and then click Add.

      Note

      Any scripts that create debug messages have their own logger, which is only created after the script has executed at least once.

      The name of the logger has the format: scripts.script_type.script_UUID.

      For example, scripts.POLICY_CONDITION.9de3eb62-f131-4fac-a294-7bd170fd4acb.

4. In the Level column, select the debug level to apply to the class.

5. In the Appender column, select the destination for the messages logged by the class.

6. Repeat the process of setting the level and appender for each class that you need to debug.

   Tip

   To set the level for all classes, choose an option from the Set level for all loggers list, and then click Apply.

7. (Optional) To remove a logger from the list, click the corresponding Remove button.

   You may need to remove loggers if they are more specific than the logger you want to configure. For example, to use the ROOT logger, you must remove all other loggers, or they will override their respective classes.

8. When finished, click the Save button at the bottom of the page.

   An Update completed message is shown at the top of the Logback.jsp page.

   Important

   Changes made in Logback.jsp apply immediately, but are not permanently stored. Restarting AM or the container in which it runs will reset the levels to defaults.

   You can configure the default settings that will be applied when AM starts up. See "Altering the Startup Debug Settings".

9. Promptly reproduce the problem you are investigating.

10. After reproducing the problem, immediately return to the Logback.jsp page, and revert to normal log levels to avoid filling up the disk where debug logs are stored.

Debug logging can be enabled and persisted in AM by configuring a logback.xml file. The file describes the classes to capture the debug messages for, and the destination, or appender where the output is stored. For more information about configuring Logback, see Logback configuration in the Logback Documentation.

Perform the following steps to configure a basic, persistent debug logging setup in AM using a logback.xml file:

1. Create a logback.xml file in the AM classpath, for example in /path/to/tomcat/webapps/openam/WEB-INF/classes/.

2. In the logback.xml file, add an empty, top-level element named configuration.

   For example:

   <configuration>
   </configuration>

   This element contains the configuration of the loggers and appenders, covered in later steps.

   1. (Optional) To instruct AM to periodically check the logback.xml file for changes, and apply them to the running instance, add both a scan and a scanPeriod attribute to the <configuration> element. For example:

      <configuration scan="true" scanPeriod="30 seconds">
      </configuration>

      Tip

      If AM is not configured to scan the logback.xml file for changes, you will need to reboot the instance in order to pick up any changes.

      You can set the scanPeriod attribute to a longer time period, for example one hour, so that rebooting a running system is not required when you need to alter the debugging level.

      For more information, see Automatically reloading configuration file upon modification in the Logback Documentation.

   2. (Optional) To troubleshoot issues when configuring debug logging using the logback.xml file, add a debug attribute, set to true, to the <configuration> element. For example:

      <configuration debug="true">
      </configuration>

      AM will record debug logging status information to the default log file for the container in which it is running. For example, in Tomcat, status messages about the configuration of logback will be recorded in the Catalina.out file.

      For more information, see Status data in the Logback Documentation.

3. Inside the <configuration> element, add the definition of one or more appenders. The following example appender logs messages to a file named debug.out in the default AM debug directory:

   <configuration>
     <appender name="DEBUG.OUT" class="ch.qos.logback.core.FileAppender">
       <file>openam/var/debug/debug.out</file>
       <encoder>
         <pattern>%lo{5}: %d{ISO8601}: Thread[%t]: TransactionId[%X{transactionId}]%n%level: %m%n%ex</pattern>
       </encoder>
     </appender>
   </configuration>

   The pattern in the above example creates debug log entries that are identical to the output produced by previous versions of AM, including the transaction ID to aid with tracking events as they occur throughout the system.

4. Inside the <configuration> element, add the definition of one or more loggers.

   Loggers specify which classes to capture debug messages from, including any sub-classes. They also specify the level of debug information to capture, and which of the specified appenders is used to store the output.

   The following example logger applies the Debug level to the scripts.POLICY_CONDITION class and its sub-classes. The output is recorded in the file specified in the debug.out appender, created in a previous step:

   <configuration>
     <appender name="DEBUG.OUT" class="ch.qos.logback.core.FileAppender">
       <file>openam/var/debug/debug.out</file>
       <encoder>
         <pattern>%lo{5}: %d{ISO8601}: Thread[%t]: TransactionId[%X{transactionId}]%n%level: %m%n%ex</pattern>
       </encoder>
     </appender>
     <logger name="scripts.POLICY_CONDITION" level="Debug" >
       <appender-ref ref="DEBUG.OUT" />
     </logger>
   </configuration>

5. (Optional) Inside the <configuration> element, add a root catch-all logger, to specify the global level of debug logging to all classes that do not match any of the loggers created in the previous step:

   <configuration>
     <appender name="DEBUG.OUT" class="ch.qos.logback.core.FileAppender">
       <file>openam/var/debug/debug.out</file>
       <encoder>
         <pattern>%lo{5}: %d{ISO8601}: Thread[%t]: TransactionId[%X{transactionId}]%n%level: %m%n%ex</pattern>
       </encoder>
     </appender>
     <logger name="scripts.POLICY_CONDITION" level="Debug" >
       <appender-ref ref="DEBUG.OUT" />
     </logger>
     <root level="Error">
       <appender-ref ref="DEBUG.OUT" />
     </root>
   </configuration>

6. Save your changes.

   The changes will be applied the next time you reboot AM or the container in which it runs.

   Note

   If you are editing an existing logback.xml that AM has already loaded, and contains the scan="true" attribute, you do not need to reboot. Instead wait for the amount of time specified in the scanPeriod attribute and the new configuration will be loaded into AM.

7. (Optional) To verify that the configuration from the logback.xml file has loaded, navigate to the Logback.jsp file, for example at https://openam.example.com:8443/openam/Logback.jsp, which reflects the configuration found:

   

   Note that any changes made in the Logback.jsp are temporary, and are not persisted to the logback.xml file.

Logback provides built-in support for a number of log file rotation schemes, for example both time and size based rotation. If you have configured AM with a logback.xml file, you can configure log file rotation in the appenders, by performing the following steps:

1. Edit the logback.xml file you created in the AM classpath, for example in /path/to/tomcat/webapps/openam/WEB-INF/classes/.

   If you need to create the file, see "To Enable Persistent Debug Logging with Logback.xml".

2. In the <configuration> element, create an appender that uses the ch.qos.logback.core.rolling.RollingFileAppender class, for example:

   <appender name="DAILYLOG" class="ch.qos.logback.core.rolling.RollingFileAppender">
     <encoder>
       <pattern>%lo{5}: %d{ISO8601}: Thread[%t]: TransactionId[%X{transactionId}]%n%level: %m%n%ex</pattern>
     </encoder>
   </appender>

   Within the appender, specify whether to rotate based on time, and optionally also size, as follows:

   1. (Optional) To rotate the log files based only on time, add a <rollingPolicy> element to the appender, which uses the ch.qos.logback.core.rolling.TimeBasedRollingPolicy class.

      Include a <fileNamePattern> element that defines when the log files should roll over, and the naming convention.

      For example, the following appender rolls the log file over at midnight each day, and includes the date in the filename:

      <appender name="DAILYLOG" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
          <fileNamePattern>openam/var/debug/dailyLog.%d{yyyy-MM-dd}.log</fileNamePattern>
        </rollingPolicy>
        <encoder>
          <pattern>%lo{5}: %d{ISO8601}: Thread[%t]: TransactionId[%X{transactionId}]%n%level: %m%n%ex</pattern>
        </encoder>
      </appender>

   2. (Optional) To rotate the log files based on both time and size, add a <rollingPolicy> element to the appender, which uses the ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy class.

      Include a <fileNamePattern> element that defines when the log files should roll over, and where the counter for rolling over based on size occurs, specified by including %i. You must also include a <maxFileSize> element to define the maximum size of the log files.

      For example, the following appender rolls the log file over at midnight each day, but earlier if the file reaches 2 gigabytes in size, and includes the date in the filename:

      <appender name="DAILYLOG2GB" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
          <fileNamePattern>openam/var/debug/dailyLog2GB.%d{yyyy-MM-dd}-%i.log</fileNamePattern>
          <maxFileSize>2GB</maxFileSize>
        </rollingPolicy>
        <encoder>
          <pattern>%lo{5}: %d{ISO8601}: Thread[%t]: TransactionId[%X{transactionId}]%n%level: %m%n%ex</pattern>
        </encoder>
      </appender>

3. Save your changes.

   The changes will be applied the next time you reboot AM or the container in which it runs.

   Note

   If you are editing an existing logback.xml that AM has already loaded, and contains the scan="true" attribute, you do not need to reboot. Instead wait for the amount of time specified in the scanPeriod attribute and the new configuration will be loaded into AM.

   Debug log files will roll over each night, and also if they reach the 2GB size limit. The file names will contain the date, and a counter to signify the order in which they were written.