14.1 Configuring and Leveraging log4j

Configuring and Leveraging log4j

Objective 6.1 is configure and leverage log4j. Most IdentityIQ troubleshooting starts by making the right component talk more, so you need to know where logging is configured, how to change it safely, and how to read what comes back.

Where Logging Is Configured

IdentityIQ uses Apache Log4j 2. Its configuration file is log4j2.properties, in identityiq_home/WEB-INF/classes. SailPoint's own instructions refer to it, for example: "add these entries to the log4j2.properties file" to troubleshoot Rapid Setup.

The file has three kinds of definitions:

Loggers inherit from their parent package and ultimately from the root logger. The most specific logger wins, so you can set sailpoint to WARN and one class to DEBUG.

Turning On Debug Logging

The documentation's Rapid Setup example shows the Log4j 2 properties syntax, a pair of lines per logger:

logger.rapidsetup.name=sailpoint.rapidsetup
logger.rapidsetup.level=debug
logger.rapidsetuplib.name=sailpoint.workflow.RapidSetupLibrary
logger.rapidsetuplib.level=debug

The part after logger. (for example, rapidsetup) is just an identifier that ties the two lines together. It must be unique in the file.

Categories Worth Knowing

Specific tasks sometimes need their own entries. The documentation, for example, tells you to add a logger entry to enable logging for the Application Builder task.

Appenders and Output

The appenders in log4j2.properties decide where messages go. A console (stdout) appender sends output to the application server's own log. A file appender writes to a separate IdentityIQ log file that can rotate by size or date. Each logger can point to one or more appenders, and output also flows up to the root logger's appenders unless additivity is turned off. When you cannot find your debug output, check three things: that the logger's level is low enough, that it reaches an appender, and that you are reading the log file on the host that actually ran the work.

A useful pattern is a dedicated file appender for a project's custom rules. Custom output then does not get lost among product messages, and it can be collected separately.

Reloading Without a Restart

• Console: the logConfig command reloads the Log4j configuration from log4j2.properties into the running instance.
• Debug pages: the Logging page shows, and can change, the path to the Log4j properties file the server uses.
• Import files: an import file's ImportAction can include logConfig (section 3.1).

In a cluster, each host has its own copy of log4j2.properties and reloads independently. Change and reload it on the host that runs the work you are debugging, or on all hosts.

Logging From Rules and Workflows

Every rule gets a log variable (section 9.2). For long-lived code, use a named logger so the rule's output can be switched on or off in log4j2.properties alone:

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
Log rlog = LogFactory.getLog("acme.rules.HRCorrelation");
if (rlog.isDebugEnabled()) {
    rlog.debug("Correlating account " + account.getIdentity());
}

logger.acmehr.name=acme.rules.HRCorrelation
logger.acmehr.level=debug

In workflows, the Standard Workflow Handler's log method writes to Log4j with a level, and the trace variable prints step-by-step execution (section 10.3). The documentation suggests println only for temporary debugging, removed before production.

Good Practice

• Debug is expensive. Verbose logging on aggregation or refresh classes can slow tasks and fill disks. Turn it on for the shortest time on the host doing the work, then set it back.
• Guard expensive messages with isDebugEnabled().
• Never log secrets, such as passwords, tokens, or full ResourceObjects with sensitive attributes.
• Keep log4j2.properties in the build (section 3.1). Each environment may need different levels and appenders.
• Know what reaches the database. Only WARN, ERROR, and FATAL events are stored in the Syslog table (section 14.2). DEBUG and INFO go only to the appenders.

Worked Troubleshooting Example

Accounts from a new JDBC application arrive, but several correlate to the wrong identities.

1. Add DEBUG loggers for sailpoint.api.Aggregator and the custom correlation rule's named logger.
2. Run logConfig in the console on the task host.
3. Re-aggregate a small test set, for example by filtering the source.
4. Read the log: which correlation key and value did the rule return for each account?
5. Fix the rule, set the loggers back to WARN, and run logConfig again.