Garbage-collection (GC) logging is a helpful diagnostic tool for troubleshooting a variety of issues that are related to the performance of microservices in a SAS Viya environment. To enable garbage-collection logging for a microservice in a SAS Viya 3.x environment, follow the instructions below. Note that these instructions apply for Viya 3.x versions only, such as SAS Viya 3.5.

Enable Garbage-Collection Logging for UNIX Environments:

These instructions, for UNIX operating environments, use the generic placeholder microservice-name for any microservice for which you want to enable GC logging in SAS Viya. Replace microservice-name with the name of the microservice of interest that you want to enable GC logging for. A note is added to each step below where modifications are necessary, with examples shown for different microservices.

Submit the following command to navigate to the /opt/sas/viya/config/etc/sysconfig/ directory on your SAS Viya server (on the same machine where the microservice of interest is running.)

cd /opt/sas/viya/config/etc/sysconfig/

2. Create a file in that directory named microservice-name.conf. Ensure that this file has the same permissions as the other files and subfolders in that directory.

Note: Name this .conf file such that it reflects the microservice for which you want to enable GC logging. For example, if you are working with the files service, you should create a file named files.conf. Or, if you are working with the SAS logon service, create a file named saslogon.conf.

3. Add the following contents to the microservice-name.conf file that you just created (/opt/sas/viya/config/etc/sysconfig/microservice-name.conf):

export JAVA_OPTION_PRINTGCDETAILS=-XX:+PrintGCDetails
export JAVA_OPTION_PRINTGCTIMESTAMPS=-XX:+PrintGCTimeStamps
export JAVA_OPTION_PRINTGCDATESTAMPS=-XX:+PrintGCDateStamps
export JAVA_OPTION_PRINTHEAPATGC=-XX:+PrintHeapAtGC
export JAVA_OPTION_VERBOSEGC=-verbose:gc
export JAVA_OPTION_LOGGC=-Xloggc:/opt/sas/viya/config/var/log/gc_`basename "$0"`_`date +%d%b%Y_%H.%M.%S`.log

4. Save the file and restart the microservice by submitting the appropriate command on the machine where the microservice runs, as shown below:

sudo service sas-viya-microservice-name-default restart

Note: Restart the applicable service for which you are enabling GC logging. For example, if you are working with the files service and you created a file that is named files.conf, use this command to restart the files service:

sudo service sas-viya-files-default restart

If you are working with the SAS logon service and you have a file that is named saslogon.conf, use this command to restart the service:

sudo service sas-viya-saslogon-default restart

After you restart the services, you should see a file that is named gc_microservice-name_date.log in the /opt/sas/viya/config/var/log directory. Each time you restart the Java virtual machine (JVM), the file name will be updated with the current date and time.

Disable Garbage-Collection Logging for UNIX Environments:

The impact of GC logging on the JVM process is fairly minimal. Therefore, you can safely leave this logging enabled long term if needed.

To disable the GC logging, simply delete the microservice-name.conf file you created in step 2, and then restart the service.

Note: This instruction to delete the microservice-name.conf file assumes that the file does not contain JVM options other than those that enable GC logging. If microservice-name.conf does contain other JVM options file, you can remove only the GC logging options that you added in step 3, rather than deleting the entire file.

Enable Garbage-Collection Logging for Windows Environments:

These instructions, for Windows operating environments, use the generic placeholder microservice-name for any microservice for which you want to enable GC logging in SAS Viya. Replace microservice-name with the name of the microservice of interest that you want to enable GC logging for. A note is added to each step below where modifications are necessary, with examples shown for different microservices.

On your SAS Viya Server (on the same machine on which the microservice of interest is running), open a Command Prompt window using "Run as administrator."
Navigate to the folder containing the sas-boostrap utility by running the command:

cd C:\Program Files\SAS\Viya\bin

Run the following commands to add the JVM options necessary to enable GC logging. Replace the microservice-name placeholder with the name of the microservice you want to enable GC logging for. The first five commands listed below contain the placeholder that needs to be replaced. The last command listed below contains the placeholder twice.

sas-bootstrap-config --token-file C:\ProgramData\SAS\Viya\etc\SASSecurityCertificateFramework\tokens\^
consul\default\management.token kv write --force -key config/microservice-name/jvm/JAVA_OPTION_PRINTGCDETAILS -value -XX:+PrintGCDetails

For example, here is what one of these commands will look like if you are enabling GC logging for the files service:

sas-bootstrap-config --token-file C:\ProgramData\SAS\Viya\etc\SASSecurityCertificateFramework\tokens\^
consul\default\management.token kv write --force -key config/files/^
jvm/JAVA_OPTION_PRINTGCDETAILS -value -XX:+PrintGCDetails

For example, here is what one of these commands will look like if you are enabling GC logging for the SAS Logon service:

sas-bootstrap-config --token-file C:\ProgramData\SAS\Viya\etc\SASSecurityCertificateFramework\tokens\^
consul\default\management.token kv write --force -key config/SASLogon/jvm/JAVA_OPTION_PRINTGCDETAILS -value -XX:+PrintGCDetails

If you have any questions about how to properly form these commands for the microservice that you want to enable logging for, contact SAS Technical Support for assistance.

Restart the microservice in Windows Services. More information about stopping and starting individual SAS microservices can be found in the General Servers and Services: Operate (Windows) section of the SAS Viya 3.5 Administration documentation.

After you restart the service, you should see a file named gc_<microservice_name>_<date>_<time>.log in the C:\ProgramData\SAS\Viya\var\log\ directory. Each time you restart the Java virtual machine (JVM), the file name is updated with the current date and time.

For example, if you are enabling GC logging for the files service, you should restart SAS File Service in Windows Services. Then, you should see a log file named gc_files_<date>_<time>.log.

Disable Garbage-Collection Logging for Windows Environments:

The impact of GC logging on the JVM process is fairly minimal. Therefore, you can safely leave this logging enabled long term if needed.

To disable the GC logging, use the following steps:

On your SAS Viya Server (on the same machine on which the microservice of interest is running), open a Command Prompt window using "Run as administrator."
Navigate to the folder containing the sas-boostrap utility by running the command:

cd C:\Program Files\SAS\Viya\bin

Run the following commands to delete the JVM options that were added to enable GC logging. Replace the microservice-name placeholder with the name of the microservice that you enabled GC logging for. Each command below contains that placeholder once that needs to be replaced.

sas-bootstrap-config --token-file C:\ProgramData\SAS\Viya\etc\SASSecurityCertificateFramework\tokens\^
consul\default\management.token kv delete config/microservice-name/jvm/JAVA_OPTION_PRINTGCDETAILS

sas-bootstrap-config --token-file C:\ProgramData\SAS\Viya\etc\SASSecurityCertificateFramework\tokens\^
consul\default\management.token kv delete config/microservice-name/^
jvm/JAVA_OPTION_VERBOSEGC

sas-bootstrap-config --token-file C:\ProgramData\SAS\Viya\etc\SASSecurityCertificateFramework\tokens\^
consul\default\management.token kv delete config/microservice-name/^
jvm/JAVA_OPTION_LOGGC

For example, here is what one of these commands will look like if you are disabling GC logging for the files service:

sas-bootstrap-config --token-file C:\ProgramData\SAS\Viya\etc\SASSecurityCertificateFramework\tokens\^
consul\default\management.token kv delete config/files/jvm/JAVA_OPTION_PRINTGCDETAILS

For example, here is what one of these commands will look like if you are disabling GC logging for the SAS Logon service:

sas-bootstrap-config --token-file C:\ProgramData\SAS\Viya\etc\SASSecurityCertificateFramework\tokens\^
consul\default\management.token kv delete config/SASLogon/jvm/^
JAVA_OPTION_PRINTGCDETAILS

Restart the microservice in Windows Services. More information about stopping and starting individual SAS microservices can be found in the General Servers and Services: Operate (Windows) section of the SAS Viya 3.5 Administration documentation.

For example, if you are disabling GC logging for the files service, you should restart SAS File Service in Windows Services. After that, you should no longer see a new gc_<microservice_name>_<date>_<time>.log created in the C:\ProgramData\SAS\Viya\var\log\ directory each time you restart that microservice.

Enabling garbage-collection logging for SAS® Viya® 3.x environments

Enable Garbage-Collection Logging for UNIX Environments:

Disable Garbage-Collection Logging for UNIX Environments:

Enable Garbage-Collection Logging for Windows Environments:

Disable Garbage-Collection Logging for Windows Environments: