How do I add logging to Groovy scripts in IDM (All versions)?

Background Information

Groovy in IDM can either use the SLF4J logging facility or java.util logging depending on which Logger class you import into your script. By default, the logger outputs logging to the standard IDM log.

SLF4J and Groovy log levels

There are five different log levels available for Groovy files when you use SLF4J logging, where ERROR is the least verbose as it only produces logs in the most serious circumstances through to TRACE, which is the most verbose as it provides detailed information about program execution. These logs take the following format:

And there are six different log levels available for Groovy files when you use java.util logging, where SEVERE is the least verbose as it only produces logs in the most serious circumstances through to FINEST, which is the most verbose as it provides detailed information about program execution. These logs take the following format:

Logging Level

The following table indicates how these log levels correspond to each other and also to the log levels in the logging.properties file (located in the /path/to/idm/conf directory):

The Global logging level in the logging.properties file applies to everything, including Groovy files and defaults to INFO:

You can change this if you require a different log level globally. Alternatively, you can use the SLF4J logging within a Groovy script to set logging levels that are specific to one or more Groovy scripts as demonstrated below.

Debug information

In IDM 7 and later, you can also set the following property in the boot.properties file (located in /path/to/idm/resolver) to include debug information (such as file name and line number) in Groovy exceptions:

SLF4J logging in Groovy scripts (called directly)

When Groovy scripts are called directly, for example from an endpoint, trigger or workflow, you can either use the SLF4J logging facility or java.util logging. This section details the use of the SLF4J logging facility. With SLF4J logging, you can use logger names (either explicitly or by passing a class) to configure different log levels that only apply to specific Groovy scripts.

Explicit logger name

This example demonstrates defining a custom logger name (myGroovyLogger); you can add the code from steps 1 and 2 to multiple Groovy scripts if you want to define the same log level in multiple scripts:

1. Include the following code at the top of your Groovy script to import the SLF4J logger and define your custom logger name: import org.slf4j.Logger; import org.slf4j.LoggerFactory; final Logger logger = LoggerFactory.getLogger("myGroovyLogger");
2. Include the appropriate logger code within your Groovy script where logging output is required. For example, you could add the following to output a simple message: logger.trace("Test log output message");
3. Add your logger name and required log level to the logging.properties file, for example to output at the finest log level: myGroovyLogger.level=FINESTThis example log will output to your IDM log as: Oct 24, 2017 11:24:12 AM org.slf4j.Logger$trace call FINEST: Test log output message

Logger name by passing a class

This example demonstrates using a logger name by passing a class, where the class file name is the base name of the *.groovy script when compiled. For example, if you wanted to debug the echo.groovy script (from the echo endpoint sample), you would use echo.class and echo.level in your Groovy script as follows:

1. Include the following code at the top of your Groovy script to import the SLF4J logger and define your logger name: import org.slf4j.Logger; import org.slf4j.LoggerFactory; final Logger logger = LoggerFactory.getLogger(echo.class);
2. Include the appropriate logger code within your Groovy script where logging output is required. For example, you could add the following to output a simple message: logger.trace("Test log output message for echo endpoint sample");
3. Add the logger name (in the format scriptName.level) and the required log level to the logging.properties file, for example to output at the finest log level: echo.level=FINESTThis example log will output to your IDM log as: Oct 24, 2017 11:24:12 AM org.slf4j.Logger$trace call FINEST: Test log output message for echo endpoint sample

java.util logging in Groovy scripts (called directly)

When Groovy scripts are called directly, for example from an endpoint, trigger or workflow, you can either use the SLF4J logging facility or java.util logging. This section details the use of java.util logging.

To configure java.util logging:

1. Change the Global logging level in the logging.properties file if you want a level other than INFO.
2. Include the following code at the top of your Groovy script to import the java.util logger and define the logger: java.util.logging.Logger logger = java.util.logging.Logger.getLogger ""
3. Include the appropriate logger code within your Groovy script where logging output is required. For example, you could add the following to output a simple message: logger.info("Test log output message")This example log will output to your IDM log as: Oct 24, 2017 11:24:12 AM org.forgerock.openidm.script.javascript.LoggerPropertyFactory$1$3 call INFO: Test log output message

Logging in Groovy scripts (called from Groovy connector)

When Groovy scripts are called from the Groovy connector, you can only use the SLF4J logging facility:

1. Change the Global logging level in the logging.properties file if you want a level other than INFO.
2. Include the following code at the top of your Groovy script to import the SLF4J logger: import org.identityconnectors.common.logging.Log
3. Include the following code to define the logger: logger = LoggerFactory.getLogger('logger');
4. Include the appropriate logger code within your Groovy script where logging output is required. For example, you could add the following to output a simple message: logger.info("Test log output message");This example log will output to your IDM log as: [2017-10-12 11:27:26.506] [INFO ] [org.forgerock.openicf.misc.scriptedcommon.ScriptedConfiguration evaluate]: Test log output message

You can alternatively use the log.info format as demonstrated in the scripted-rest-with-dj sample (scriptedrest2dj) (located in the /path/to/idm/samples directory). The only difference between the sample and the process above is the code used to define the logger and the format of the logger code:

• Step 3 - use the following code to define the logger: def log = log as Log
• Step 4 - use the following logger code format, that is log. instead of logger.: log.info("Test log output message");

See Also

How do I call one Groovy script from another in IDM (All versions)?

FAQ: Scripts in IDM

How do I add logging to JavaScript files in IDM (All versions)?

Log Functions

Groovy connector Toolkit

SLF4J Logger

Related Training

N/A

Related Issue Tracker IDs

N/A