Enabling garbage-collection logging for SAS® 9.4 Environments


Garbage-collection (GC) logging is a helpful diagnostic tool for troubleshooting a variety of issues that are related to the performance of SAS® Web Application Server instances. To enable GC logging for SAS Web Application Server on SAS 9.4 in Microsoft Windows or UNIX operating environments, complete the instructions below.

Note that there is a separate method for enabling this logging for SAS® 9.4M8 (TS1M8) and for SAS® 9.4M7 (TS1M7) and earlier releases. Be sure to follow the appropriate section below depending on your release. 

SAS® 9.4M8 (TS1M8)

Enable GC Logging under UNIX for SAS 9.4M8

To enable GC logging under UNIX, modify the setenv.sh file for the SAS Web Application Server instance for which you want to enable the logging. For example, to enable logging for SASServer1_1, modify the setenv.sh file that resides in the SAS-configuration-directory/LevN/Web/WebAppServer/SASServer1_1/bin directory.

To enable the garbage-collection logging, complete the following steps:

1. Add the following option within the double quotation marks of the JVM_OPTS="..." line in the setenv.sh file:  

-Xlog:gc*:file=/SAS-configuration-directory/Lev1/Web/Logs/gcSASServer1_1.log:time,tags,level,uptime
 

Note: Change the SAS-configuration-directory placeholder above to match the exact SAS configuration directory path for this environment. If you enable GC logging for a SAS Web Application Server other than SASServer1_1, change the SASServer1_1 above to match the applicable SAS Web Application Server instance (such as SASServer2_1, SASServer12_1, and so on). 

2. Restart the SAS Web Application Server instance for which you modified the setenv.sh file so that the changes can take effect. For example, SASServer1_1 can be restarted individually with a command similar to the following: 

<SAS_CONFIG>/Lev1/Web/WebAppServer/SASServer1_1/bin/tcruntime-ctl.sh restart 

3. The new gcSASServer1_1.log file should be located in the <SAS_CONFIG>/Lev1/Web/Logs/ directory. 

Enabling GC Logging under Microsoft Windows for SAS 9.4M8

To enable GC logging under Windows, modify the wrapper.conf file for the SAS Web Application Server for which you want to enable logging. For example, to enable logging for SASServer1_1, modify the wrapper.conf file that resides in the SAS-configuration-directory\LevN\Web\WebAppServer\SASServer1_1\conf folder.

To enable the garbage-collection logging, complete the following steps:

1. Locate the Java Virtual Machine (JVM) options that look similar to the following: wrapper.java.additional.XX=

Note: For each of the options, xx represents the next number in the sequence for the number of options that are listed.

2. After the last of these sequential JVM options, add the following new JVM option: 

wrapper.java.additional.XX=-Xlog:gc*:file=\SAS-configuration-directory\Lev1\Web\Logs\gcSASServer1_1.log:time,tags,level,uptime
  1. Change the xx placeholder to the next number in the sequence of the other JVM options in this file.
  2. Change the SAS-configuration-directory placeholder above to match the exact SAS configuration directory path for this environment. If you enable GC logging for a SAS Web Application Server other than SASServer1_1, change the SASServer1_1 above to match the applicable SAS Web Application Server instance (such as SASServer2_1, SASServer12_1, and so on). 

3. After making changes to the wrapper.conf file, you must rebuild the Windows Service for that SAS Web Application Server instance to pick up the changes. Follow the steps documented in Rebuild Windows Service for Each SAS Web Application Server Instance to rebuild the Windows Service, and then start up the SAS Web Application Server instance. 

4. The new gcSASServer1_1.log file should be located in the <SAS_CONFIG>/Lev1/Web/Logs/ directory. 

SAS® 9.4M7 (TS1M7) and Earlier Releases: 

Enable GC Logging under UNIX for SAS 9.4M7 and Earlier Releases

To enable GC logging under UNIX, you need to modify the setenv.sh file for the SAS Web Application Server instance for which you want to enable the logging. For example, to enable logging for SASServer1_1, modify the setenv.sh file that resides in the SAS-configuration-directory/LevN/Web/WebAppServer/SASServer1_1/bin directory.

To enable the GC logging, complete the following steps:

  1. Locate the following line in the setenv.sh file:
    JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBRARY_PATH"
  2. Replace that line with the following block of code:
    #-------------------------------------------
    # rjc - SAS TS diagnostics
    LEV_DIR="/SAS-configuration-directory/LevN"
    SERVER=01
    CLUSTER=1
    #-------------------------------------------
    PROCESS_NAME=SASServer${SERVER}_${CLUSTER}
    #- optional protocol stack, uncomment to enable.
    #PROTOCOL_STACK_URL="file:///$LEV_DIR/Web/protocolStack.xml"
    #TS_JVM_OPTS="$TS_JVM_OPTS -Dmulticast.config.file=$PROTOCOL_STACK_URL"
    # rjc - output files
    GC_LOG_FILE="$LEV_DIR/Web/Logs/gc${PROCESS_NAME}_`date +%d%b%Y_%H.%M.%S`.log" 
    ULIMIT_FILE="$LEV_DIR/Web/Logs/ulimit${PROCESS_NAME}.log"
    echo "GC data will be written to $GC_LOG_FILE"
    echo "user limits written to $ULIMIT_FILE"
    # rjc - collect user limits for this process
    echo "----------" > $ULIMIT_FILE
    date >> $ULIMIT_FILE
    echo "----------" >> $ULIMIT_FILE
    echo "ulimt -a: " >> $ULIMIT_FILE
    ulimit -a >> $ULIMIT_FILE
    echo "----------" >> $ULIMIT_FILE
    echo "ulimt -Ha: " >> $ULIMIT_FILE
    ulimit -Ha >> $ULIMIT_FILE
    TS_JVM_OPTS=""
    #rjc - enable verbose gc logging
    TS_JVM_OPTS="$TS_JVM_OPTS -XX:+PrintGCDetails -XX:+PrintGCTimeStamps"
    TS_JVM_OPTS="$TS_JVM_OPTS -XX:+PrintGCDateStamps -XX:+PrintHeapAtGC"
    TS_JVM_OPTS="$TS_JVM_OPTS -verbose:gc -Xloggc:$GC_LOG_FILE"
    #-------------------------------------------
    JAVA_OPTS="$JVM_OPTS $TS_JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBRARY_PATH"

    Note: If you are using an IBM Java Developer Kit (JDK) or Java Runtime Environment (JRE), use this block of code instead:

    #-------------------------------------------
    # rjc - SAS TS diagnostics
    LEV_DIR="/SAS-configuration-directory/LevN"
    SERVER=01
    CLUSTER=1
    #-------------------------------------------
    PROCESS_NAME=SASServer${SERVER}_${CLUSTER}
    #- optional protocol stack, uncomment to enable.
    #PROTOCOL_STACK_URL="file:///$LEV_DIR/Web/protocolStack.xml"
    #TS_JVM_OPTS="$TS_JVM_OPTS -Dmulticast.config.file=$PROTOCOL_STACK_URL"
    # rjc - output files
    GC_LOG_FILE="$LEV_DIR/Web/Logs/gc${PROCESS_NAME}_`date +%d%b%Y_%H.%M.%S`.log" 
    ULIMIT_FILE="$LEV_DIR/Web/Logs/ulimit${PROCESS_NAME}.log"
    echo "GC data will be written to $GC_LOG_FILE"
    echo "user limits written to $ULIMIT_FILE"
    # rjc - collect user limits for this process
    echo "----------" > $ULIMIT_FILE
    date >> $ULIMIT_FILE
    echo "----------" >> $ULIMIT_FILE
    echo "ulimt -a: " >> $ULIMIT_FILE
    ulimit -a >> $ULIMIT_FILE
    echo "----------" >> $ULIMIT_FILE
    echo "ulimt -Ha: " >> $ULIMIT_FILE
    ulimit -Ha >> $ULIMIT_FILE
    TS_JVM_OPTS=""
    #rjc - enable verbose gc logging
    TS_JVM_OPTS="$TS_JVM_OPTS -verbose:gc -Xverbosegclog:$GC_LOG_FILE"
    #-------------------------------------------
    JAVA_OPTS="$JVM_OPTS $TS_JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBRARY_PATH"
  3. Edit the following variables (which are in bold in the code above) as follows:
    • Set the LEV_DIR= variable to the LevN directory for this environment.
    • Set the SERVER= variable to the server number. For example, for SASServer1_1, set SERVER=01; for SASServer2_1, set SERVER=02; for SASServer12_1, set SERVER=12 (and so on).
    • Set the CLUSTER= variable to the cluster number. For example, for SASServer1_1, set CLUSTER=1; for SASServer1_2, set CLUSTER=2; for SASServer12_5, set CLUSTER=5 (and so on).
  4. Restart the SAS Web Application Server instance for which you modified the setenv.sh file so that the changes can take effect. Once you restart the application, the following new log files should be created:
    • SAS-configuration-directory/LevN/Web/Logs/gc*.log
    • SAS-configuration-directory/Lev/Web/Logs/ulimit*.log

Enabling GC Logging under Microsoft Windows for SAS 9.4M7 and Earlier Releases

To enable GC logging under Windows, modify the wrapper.conf file for the SAS Web Application Server for which you want to enable logging. For example, to enable logging for SASServer1_1, modify the wrapper.conf file that resides in the SAS-configuration-directory\LevN\Web\WebAppServer\SASServer1_1\conf folder.

To enable the garbage-collection logging, complete the following steps:

  1. Locate the Java Virtual Machine (JVM) options that look similar to the following: wrapper.java.additional.XX=

Note: For each of the options, xx represents the next number in the sequence for the number of options that are listed.

  1. After the last of these sequential JVM options, add the following block of code to the wrapper.conf file:
    #-------------------------------------------
    # rjc - SAS TS diagnostics - wrapper.conf
    set.LEV_DIR=C:/SAS-configuration-directory/Lev1
    set.SERVER=01
    set.CLUSTER=1
    #-------------------------------------------

    set.PROCESS_NAME=SASServer%SERVER%_%CLUSTER%
    set.GC_LOG_FILE=%LEV_DIR%/Web/Logs/gc%PROCESS_NAME%.log

    # rjc - build verbose gc logging options
    set.GC_OPT=-XX:+PrintGCDetails -XX:+PrintGCTimeStamps
    set.GC_OPT=%GC_OPT% -XX:+PrintGCDateStamps -XX:+PrintHeapAtGC
    set.GC_OPT=%GC_OPT% -verbose:gc -Xloggc:%GC_LOG_FILE%

    # rjc - enable diagnostic options, make sure that the sequence numbers are correct 
    wrapper.java.additional.XX=%GC_OPT%
    #-------------------------------------------
    #-------------------------------------------
  2. Edit the following items (which are in bold in the code above), as follows: 
    • Set the set.LEV_DIR= variable to the LevN directory for this environment.
    • Set the set.SERVER= variable to the server number. For example, for SASServer1_1, set SERVER=01; for SASServer2_1, set SERVER=02; for SASServer12_1, set SERVER=12 (and so on).
    • Set the set.CLUSTER= variable to the cluster number. For example, for SASServer1_1, set CLUSTER=1; for SASServer1_2, set CLUSTER=2; for SASServer12_5, set CLUSTER=5 (and so on).
    • For the wrapper.java.additional.XX = parameter, change xx to the next number in the sequence of the other JVM options in this file.
  3. Restart the SAS Web Application Server for which you modified the wrapper.conf file for so that the changes can take effect. If you are using the February 15, 2022 release of SAS 9.4M7 or later, you must also rebuild the Windows Service for the SAS Web Application Server instance after making changes to the wrapper.conf file in order for the changes to be applied. Follow the steps documented in Rebuild Windows Service for Each SAS Web Application Server Instance to do that. Once you restart the application, the following new log file should be created: SAS-configuration-directory\LevN\Web\Logs\gc*.log

Note: In Windows environments of SAS 9.4M7 and earlier, the GC log is automatically overwritten each time that SAS Web Application Server restarts. There is no workaround for this issue. (This problem does not occur in UNIX environments.) So, to avoid losing important diagnostic information when this file is overwritten, you need to implement a backup utility. For a method to implement a backup utility, see SAS Note 59142, "Backing up garbage-collection (GC) log files in Microsoft Windows operating environments." This method does not apply to SAS 9.4M8 because the GC log automatically rolls over.