IdentityIQ 8.0: Changes to logging

[#1]

Back to the IdentityIQ 8.0 overview: What’s new in IdentityIQ 8.0

• Overview
• Configuration File Name/Location
• Syntax of log4j2.properties
• Examples of Logging Syntax for IdentityIQ
• Apache Commons Logging
• Change Listening
• Upgrade Considerations
• Additional Resources

Overview

Version 8.0 of IdentityIQ uses version 2.11.1 of Log4j: Log4j2   This change adds new logging capabilities (specifically, change listening), and also means that there are changes to the the logging configuration file name, and to logging syntax.

Configuration File Name/Location

Previously, the log4j configuration file was  WEB-INF/classes/log4j.properties.  This log4j.properties file is no longer shipped, and will not be referenced if present.

In IdentityIQ 8.0, the log4j2 configuration file is WEB-INF/classes/log4j2.properties. (Note the digit 2 in the filename.)

Syntax of log4j2.properties

Log4j2's syntax is different from log4j's. Previously in v1 in log4j.properties, the syntax was:

log4j.logger.com.acme.example=debug

In version 2 in log4j2.properties, you now declare using this syntax:

logger.acmeExample.name=com.acme.example

logger.acmeExample.level=debug

Notice the differences:

• the log4j. prefix no longer used
• 2 lines are required instead of 1
• the logger identifier value (acmeExample) is not important, other than it is uniquely used to join the two lines together

In IdentityIQ 8.0, the previous log4j.properties have been fully converted into the new syntax in the log4j2.properties file. You can refer to Apache's Log4j – Configuring Log4j 2 - Apache Log4j 2​  document for a full description of log4j2 configuration.

Examples of Logging Syntax for IdentityIQ

The log4j2.properties file that is shipped with IdentityIQ version 8.0 includes statements for SailPoint loggers.Some are enabled by default and others provide commented-out statements; in these cases you can simply un-comment the statements that provides the logging you want. Here are some examples:

Hibernate Example

logger.orgHibernate.name=org.hibernate

logger.orgHibernate.level=trace

Aggregator Example

logger.aggregator.name=sailpoint.api.Aggregator

logger.aggregator.level=trace

Sailpoint Connector Example

logger.sp_connectorName.name=sailpoint.connector.ConnectorName

logger.sp_connectorName.level=debug

OpenConnector Example for Okta

logger.okta.name=openconnector.connector.Okta

logger.okta.level=trace

Apache Commons Logging

As with previous releases, with version 8.0 it is recommended that classes which perform simple logging use org.apache.commons.logging. For example:

import org.apache.commons.logging.Log;

import org.apache.commons.logging.LogFactory;

…

private static Log log = LogFactory.getLog(MyClass.class);

…

log.info("printing message 1");

Change Listening

Listening for, and automatically enforcing, changes to the logging configuration is a new feature of log4j2. IdentityIQ's default log4j2.properties declares a monitorInterval of 20 seconds, so changes will be enforced within 20 seconds of saving changes to log4j2.properties.

You can turn off change listening by setting the property monitorInterval to 0 in log4j2.properties.

Upgrade Considerations

As part of your upgrade to IdentityIQ version 8.0, you must edit the new log4j2.properties file to reflect any customizations you may have made to your prior version of IdentityIQ. The sample logging statements in the log4j2.properties file can help you with the log4j2 logging syntax.

Also, any rules that that use log4j logging may require updating, and verification that they are importing correctly. If there are tools, plugins, or other custom code written that used log4j v1 APIs (typically to modify logging configurations), those will need to be rewritten to use the new log4j v2 APIs in order to work for IdentityIQ 8.0. For more information, refer to the section on Converting to the Log4j 2 API in Migrating from Log4j 1.x

NOTE: There is some  support for backward-compatibility with basic log4j v1 APIs, due to the inclusion of the log4j-1.2-api-2.11.2.jar.  But, as mentioned earlier, the apache commons-logging should be used for the basic logging calls.

Additional Resources

For more information on Log4j2, refer to these Apache documents:

• Apache Log4j2
• Log4j2 overview
• Configuration
• Migrating from Log4j 1.x

For more information on logging in IdentityIQ, see . Although this document is written for the earlier version of log4j, it includes general guidance about logging that is useful regardless of the version of log4j you are using.

[michael_bullock]

I'd like to suggest an addition to the section, Syntax of log4j2.properties.

I noticed while trying to migrate my old log4j.properties logger entries into the new format that each dot delimited section of a logger needs explicit declaration.  For instance, if I want to declare a logger like:

logger.bob.test.junk.name=bob.test.junk

I must first declare the 'parents', 'bob' and 'test' like:

logger.bob.name=bob

logger.bob.test.name=bob.test

The name value (after the seems less important to log4j2 than the explicit declaration of the parent nodes. 

Suggest modifying the section to say:

Notice the differences:

• the log4j. prefix no longer used
• 2 lines are required instead of 1
• the logger identifier value (acmeExample) is not important, other than it is uniquely used to join the two lines together
• each dot delimited entry between 'logger' and 'name' must be explicitly declared with its own logger entry