SailPoint proper way to construct a rolling log file

There is some confusion of how to set up the log4j2.properties file in order to log to a rolling log file.  Here is what the OOTB log4j2.properties file shows:

# Below is an example of how to create a logger that writes to a file.

# Uncomment the following five lines, then uncomment the 

# rootLogger.appenderRef.file.ref definition below

#appender.file.type=File

#appender.file.name=file

#appender.file.fileName=C:/Windows/Temp/sailpoint.log

#appender.file.layout.type=PatternLayout

#appender.file.layout.pattern=%d{ISO8601} %5p %t %c{4}:%L - %m%n

This setup does not roll.  The file also contains the following:

#appender.meter.type=RollingFile

#appender.meter.name=meter

#appender.meter.fileName=C:/Windows/Temp/meter.log

#appender.meter.filePattern=C:/Windows/Temp/meter-%d{yyyy-MM-dd}-%i.log.gz"

#appender.meter.layout.type=PatternLayout

#appender.meter.layout.pattern=%m%n

#appender.meter.policies.type=Policies

#appender.meter.policies.size.type=SizeBasedTriggeringPolicy

#appender.meter.policies.size.size=10MB

#appender.meter.strategy.type=DefaultRolloverStrategy

#appender.meter.strategy.max=5

The main issue with this is the use of the date and the gzip options.  It also doesn't have the proper pattern layout.

The best practice is something like this:

appender.rolling.type=RollingFile

appender.rolling.name=rolling

appender.rolling.fileName=D:/iiq83/logs/sailpoint.log

appender.rolling.filePattern=D:/iiq83/logs/sailpoint-%i.log"

appender.rolling.layout.type=PatternLayout

appender.rolling.layout.pattern=%d{ISO8601} %5p %t %c{4}:%L - %m%n

appender.rolling.policies.type=Policies

appender.rolling.policies.size.type=SizeBasedTriggeringPolicy

appender.rolling.policies.size.size=20MB

appender.rolling.strategy.type=DefaultRolloverStrategy

appender.rolling.strategy.max=5

The word "rolling" can be substituted by any other name.  Be sure to leave out the date and the gzip references in the filePattern part.

Some advice: Never use the time based policy.  Never use the startup policy.  With this method you can archive files by their age.

Usage for this includes the following to make sure the files are correctly being written to:

rootLogger.level=warn

rootLogger.appenderRef.stdout.ref=stdout

rootLogger.appenderRef.rolling.ref=rolling

And all logging should be structured like this:

logger.objexp.name=com.sailpoint.objectexporter.task

logger.objexp.level=trace

logger.objexp.appenderRef.rolling.ref=rolling

logger.objexp.additivity=false

The second portion of this block, must be unique.

The file name you chose, should be provided in the third line in two places as shown.

SailPoint logging best practice

SailPoint recommends using the log4j calls for logging.  This is in contrast to the occasional use of commons logging in some of their codes.  Just for reference:

import org.apache.log4j.Logger;

Logger alog=Logger.getLogger("com.sailpoint.class.module");

The above creates the Logger class and uses log4j (BEST)

import org.apache.commons.logging.Log;

import org.apache.commons.logging.LogFactory;

Log alog=LogFactory.getLog("com.sailpoint.class.module");

The second example uses the commons logging and is not best, but works.  Commons logging actually uses log4j so it's a needless extra layer.

Providing proper construction, level, and content for log statements is important.  Why do we use logging instead of a debugger? Because for most web applications, you can't pause the program to inspect its variables.  Logging is the best option. 

Some people, generally those who don't understand log4j, will start with a statement like:

log.error("I am here");

and then later something like:

log.error("Now I am here");

Let's examine the errors in this method of troubleshooting:

1) Use of an OOTB log object.

2) Using error call for simple debugging.

3) General lack of information about "where" you are in the program.

4) Lack of any meaningful information in the log output.

In more detail:

1) Never use an OOTB log object, always create a new one.  I always call mine alog but you could call your blog or clog, go nuts.  I have seen plogger and others, but I don't like to type so alog fits my style.  You could overwrite log also but I don't recommend that.

2) Learn the log levels and their meaning.  TRACE is the most verbose and should be confined to inner loops in iterative code, that you would expect to print if there is a very insidious logic issue you are trying to track down.  DEBUG is best for debugging code and should be used for most log statements.  INFO is rarely used but could be used for method entry statements. WARN is the first level of statements that the OOTB log setup will always print, and should be a warning. ERROR should be used in catch blocks and anywhere a severe error is found.  Their respective methods, trace(), debug(), info(), warn(), and error() send this data to the logger.  You have to learn how to set the log levels in the log4j2.properties file (or log4j.properties for older versions).

3) In the text of your log statement, provide a coded prefix or "tag" that indicates the initials of the client, a 3 or 4 character module code, and a unique number.  For example, for Acme's WorkDay customization rule, the prefix on the first log statement will be something like "ACM-WDC-001" and the final logging would be something like:

String fileNumber=(String)object.getAttribute("FILENUMBER");

alog.debug("ACM-WDC-001 Entered WorkDay Customization rule for user "+fileNumber);

Each different module has a unique 3 or 4 character module code and each log statement has a unique number, which does not have to be strictly sequential.

4) Notice above that the log statement contains information about what is happening, rather than just a dead line "I am here".  Always try to include data and don't forget to null check things before printing.

Use of these techniques also makes troubleshooting with your SIEM more effective.