20 Configuring Logging

Oracle Identity Manager uses two logging services: Oracle Diagnostic Logging (ODL), which is the logging service used by most Oracle Fusion Middleware applications, and Apache log4j.

Oracle Identity Manager logging is primarily done with ODL. Apache log4j is only used with third-party applications, such as Nexaweb for Deployment Manager and Workflow Designer, and OSCache for caching.

This chapter contains the following sections:

20.1 Logging in Oracle Identity Manager By Using ODL

Oracle Diagnostic Logging (ODL) is the principal logging service used by Oracle Identity Manager. For ODL logging to work, both loggers and log handlers need to be configured. Loggers send messages to handlers, and handlers accept messages and output them to log files.

Logging configuration is controlled by the logging.xml file described in "Log Handler and Logger Configuration". This file can either be edited directly or edited through the Enterprise Manager. On the Enterprise Manager, the logging configuration can be accessed by clicking the OIM server link and by selecting the WebLogic Server drop down from the top, and then clicking on Logs - Log Configuration.

To access the logging configuration on the Enterprise Manager:

  1. Click the OIM server link.

  2. From the WebLogic Server list, select Logs - Log Configuration. All the packages available for logging are displayed on the log configuration screen.

For any additional packages to be logged that are not available in the Enterprise Manager (such as, for connector packages), follow the instructions to manually edit the logging.xml file. The packages specific to Oracle Identity Manager can be accessed under oracle.iam. The different log levels are available for selection under the Oracle Diagnostic Logging Level column. Select a particular log level, and then click Apply for the changes to take effect. In addition, new log handlers can be created and configured by clicking the Log Files tab.

Each Oracle Identity Manager module has its own logger that can be configured independently to send different amounts of information to one or more log handlers. Table 20-2, "Oracle Identity Manager Loggers" lists the more than twenty different Oracle Identity Manager loggers that can be configured to send messages to log handlers.

You can output more or less information to a log by adjusting the level attribute for each logger. To select a logging level, choose from one of five message types (INCIDENT_ERROR, ERROR, WARNING, NOTIFICATION, and TRACE). Each message type can also take a numeric value between 1 (highest severity) and 32 (lowest severity) that you can use to further restrict the volume of messages that a logger will output. Table 1 on page 2 lists the message type and level combinations that are used most often.

Log handlers specify the target where log messages should appear. For example, log handlers can write messages to the console, to various log files, and to additional outputs.

This section contains the following topics:

20.1.1 Message Types and Levels

ODL recognizes five message types: INCIDENT_ERROR, ERROR, WARNING, NOTIFICATION, and TRACE. Each message type can also take a numeric value between 1 (highest severity) and 32 (lowest severity) that you can use to further restrict message output.

When you specify a message type, ODL returns all messages of that type, as well as the messages that have a higher severity. For example, if you set the message type to WARNING, ODL also returns messages of type INCIDENT_ERROR and ERROR.

Message types and levels are described in greater detail in "Setting the Level of Information Written to Log Files" of the Oracle Fusion Middleware Administrator's Guide. Table 20-1 lists the diagnostic message types that you can use most often with Oracle Identity Manager.

Table 20-1 Oracle Identity Manager Diagnostic Message Types

Message Type and Numeric Value Description

INCIDENT_ERROR:1

A serious problem that may be caused by a bug in the product and that should be reported to Oracle Support.

Examples are errors from which you cannot recover.

ERROR:1

A serious problem that requires immediate attention from the administrator and is not caused by a bug in the product.

An example is if Oracle Fusion Middleware cannot process a log file, then you can correct the problem by fixing the permissions on the document.

WARNING:1

A potential problem that should be reviewed by the administrator.

Examples are invalid parameter values or a specified file does not exist.

NOTIFICATION:1

A major lifecycle event such as the activation or deactivation of a primary sub-component or feature.

This is the default level for NOTIFICATION.

NOTIFICATION:16

A finer level of granularity for reporting normal events.

TRACE:1

Trace or debug information for events that are meaningful to administrators, such as public API entry or exit points.

TRACE:16

Detailed trace or debug information that can help Oracle Support diagnose problems with a particular subsystem.

TRACE:32

Very detailed trace or debug information that can help Oracle Support diagnose problems with a particular subsystem.


20.1.2 Log Handler and Logger Configuration

Both log handlers and loggers can be configured by editing logging.xml, which is located in:

DOMAIN_NAME/config/fmwconfig/servers/SERVER_NAME/logging.xml

Here, DOMAIN_NAME and SERVER_NAME are the domain name and server name respectively specified during the installation of Oracle Identity Manager.

The logging.xml file has a <log_handlers> configuration section, followed by a <loggers> configuration section. Each log handler is defined within the <log_handlers> section, and each logger is defined within the <loggers> section.

The file has the following basic structure:

<logging configuration>
  <log_handlers>
    <log_handler name='console-handler' level="NOTIFICATION:16"></log_handler>
    <log_handler name='odl-handler'></log_handler>
    <!--Additional log_handler elements defined here....-->
  </log_handlers>
  <loggers>
    <logger name="example.logger.one" level="NOTIFICATION:16">
      <handler name="console-handler"/>
    </logger>
    <logger name="example.logger.two" />
    <logger name="example.logger.three" />
    <!--Additional logger elements defined here....-->
  </loggers>
</logging_configuration>

When configuring a logger to write messages to either the console or a file, make configuration changes to both the logger and the handler. Setting the level attribute for the logger configures the amount of detail (and therefore, the volume of messages) that the logger sends to the handler. Similarly, setting the level attribute for the handler configures the amount of detail that the handler accepts from the logger.

Note:

If you are not getting the volume of output that you expect in a log, then verify that the level attribute for both the logger and the log handler are set appropriately. For example, if the logger is set to TRACE and the log handler is set to WARN, then the handler does not generate messages more detailed than WARN.

20.1.3 Configuring Log Handlers

Individual log handlers are configured in the <log_handlers> section of the logging.xml file. Configure the level attribute for the handler to set the amount of detail that the handler will accept from loggers.

To configure the log handler-level attribute:

Note:

You must have a basic understanding of XML syntax before you attempt to modify the logging.xml file.

  1. Open the DOMAIN_NAME/config/fmwconfig/servers/SERVER_NAME/logging.xml file.

  2. Change the level attribute as shown in the following examples.

    In this example XML code, the level attribute for the console-handler is set to WARNING:32.

    <log_handler name='console-handler' class='oracle.core.ojdl.logging.ConsoleHandler' formatter='oracle.core.ojdl.weblogic.ConsoleFormatter' level='WARNING:32'/>
    

    For the console-handler to be able to write TRACE level messages to the console, change the level attribute as shown:

    <log_handler name='console-handler' class='oracle.core.ojdl.logging.ConsoleHandler' formatter='oracle.core.ojdl.weblogic.ConsoleFormatter' level='TRACE:1'/>
    
  3. Save your changes and restart the application server.

20.1.3.1 Log Handler Configuration Tools

Log handlers that write to a file have additional properties that can be configured. For example, this excerpt from logging.xml configures the odl-handler:

<log_handler name='odl-handler' class='oracle.core.ojdl.logging.ODLHandlerFactory'     filter='oracle.dfw.incident.IncidentDetectionLogFilter'>
    <property name='path'     value='${domain.home}/servers/${weblogic.Name}/logs/${weblogic.Name}-diagnostic.log'/>
    <property name='maxFileSize' value='10485760'/>
    <property name='maxLogSize' value='104857600'/>
    <property name='encoding' value='UTF-8'/>
    <property name='useThreadName' value='true'/>
    <property name='supplementalAttributes' value='J2EE_APP.name,J2EE_MODULE.name,     WEBSERVICE.name,WEBSERVICE_PORT.name,composite_instance_id,component_instance_id,     composite_name,component_name'/>
</log_handler>

To make changes to log handler properties, you can use either the Fusion Middleware Control tool or the WLST command-line tool.

See Also:

  • "Configuring Settings for Log Files" in the Oracle Fusion Middleware Administrator's Guide for information about both the Fusion Middleware Control tool and the WLST command-line tool

  • "Logging Custom WLST Commands" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for information about the WLST command-line tool

20.1.4 Configuring Loggers

Individual loggers are configured in the <loggers> section of the logging.xml file. More than twenty different Oracle Identity Manager loggers that can be configured to send messages to log handlers. Oracle Identity Manager loggers are described in Table 2 on page 7.Setting the level attribute for the logger configures the amount of detail (and, hence, the volume of messages) that the logger sends to its handlers. Nesting one or more <handler> elements inside of <logger> elements assigns handlers to loggers.The following excerpt shows a logger called OIMCP.PSFTCOMMON. The level attribute is set to WARNING:32 and the logger sends messages to three handlers:

<logger name="OIMCP.PSFTCOMMON" level="WARNING:32" useParentHandlers="false">
<handler name="odl-handler"/>
<handler name="wls-domain"/>
<handler name="console-handler"/>
</logger>

A logger can inherit a parent logger's settings, including the parent's level setting and other attributes, as well as the parent logger's handlers. To disable inheritance, set the useParentHandlers attribute to false, as shown in the previous excerpt.

At the top of the logger inheritance tree is the root logger. The root logger is the logger with an empty name attribute, as shown in the following example.

<loggers>
    <logger name="" level="WARNING:1">
      <handler name="odl-handler"/>
      <handler name="wls-domain"/>
      <handler name="console-handler"/>
    </logger>

    <!-- Additional loggers listed here -->
</loggers>

If a logger is configured with only its name attribute, the logger will inherit the rest of its attributes from the root logger, as shown in the following example:

<loggers>
    <logger name="oracle.iam.identity.rolemgmt"/>
    <!-- Additional loggers listed here -->
</loggers>

To configure loggers:

  1. Open the DOMAIN_NAME/config/fmwconfig/servers/SERVER_NAME/logging.xml file.

  2. Locate the logger you want to configure. Table 20-2 lists the Oracle Identity Manager loggers.

    Table 20-2 Oracle Identity Manager Loggers

    Logger Description
    oracle.iam.request
    oracle.iam.requestdatasetgeneration
    oracle.iam.requestactions
    oracle.iam.platform.workflowservice
    

    Logs events related to request and request dataset management.

    oracle.iam.selfservice
    

    Logs events related to authenticated and unauthenticated self-service operations.

    oracle.iam.ChangePasswordtaskflow
    

    Logs events for the password change functionality UI.

    oracle.iam.forgotpasswordtaskflow
    

    Logs events for the "forgot password" functionality UI.

    oracle.iam.identitytaskflow
    

    Logs events for the administrative UI identity operations.

    oracle.iam.identity.orgmgmt
    

    Logs events related to the organization manager service operations.

    oracle.iam.identity.rolemgmt
    

    Logs events related to the role manager service operations.

    oracle.iam.identity.usermgmt
    

    Logs events related to the user manager service operations.

    oracle.iam.identity.scheduledtasks
    

    Logs events related to scheduled tasks in the identity feature.

    oracle.iam.platform.utils
    

    Logs events related to utilities provided by the platform (mainly used by other features). Includes utilities for message resources handling, logging handling, internationalization, caching, and so on.

    oracle.iam.platformservice
    

    Logs events related to utilities that are mainly executed from the client side. For example, the plug-in registration utility, the purge cache utility, and so on. Some server-side utilities, such as the date-time utility and the exception handling utility, also use this logger.

    oracle.iam.platform.canonic
    

    Logs events related to the platform UI framework.

    oracle.iam.consoles.faces
    oracle.iam.consoles.common
    

    Logs messages generated from the UI framework.

    oracle.iam.platform.kernel
    

    Logs events related to the kernel. This includes the logging generated during the handling of orchestrations by the platform. The event handlers executed in the orchestrations within each feature use that feature's respective logger.

    oracle.iam.platform.context
    

    Logs events related to the context management feature.

    oracle.iam.platform.entitymgr
    

    Logs events related to the entity manager feature. This feature provides generic handling of different types of entities, such as users, roles, and so on, and appropriate routing to the respective operations on them.

    oracle.iam.scheduler
    oracle.iam.platform.scheduler
    Xellerate.Scheduler
    Xellerate.Scheduler.Task
    

    Logs events related to the scheduler. Note that certain scheduled tasks may also use other loggers.

    oracle.iam.reconciliation
    

    Logs events related to the reconciliation feature.

    oracle.iam.accesspolicy
    

    Logs events related to the access policy feature.

    oracle.iam.autoroles
    

    Logs events related to the auto role membership assignment feature.

    oracle.iam.callbacks
    

    Logs events related to the callbacks feature.

    oracle.iam.configservice
    

    Logs events related to the Configuration service APIs that are used for configuration of entity attributes.

    oracle.iam.ldap-sync
    

    Logs events related to the Oracle Identity Manager and LDAP synchronization feature.

    oracle.iam.notification
    

    Logs events related to e-mail templates and the notifications handling feature.

    oracle.iam.passwdmgnt
    

    Logs events related to the password management feature.

    oracle.iam.platform.pluginframework
    

    Logs events from the plug-in framework feature that handles the management of plug-ins.

    oracle.iam.platform.async
    

    Logs events from platform that handles asynchronous operations.

    oracle.iam.spmlws
    oracle.iam.wsschema
    

    Logs events related to web services used for Fusion applications that generate requests for different operations.

    oracle.iam.diagnostic
    

    Logs messages from the diagnostic service APIs used to run diagnostic checks.

    oracle.iam.oimdataproviders
    

    Logs events related to the Oracle Identity Manager data providers. The Oracle Identity Manager data providers provide code to update and fetch data from the Oracle Identity Manager database.

    Xellerate.Database
    

    Logs database operations.

    Xellerate.PreparedStatement
    

    Same as Xellerate.Database, but logs only PreparedStatement details.

    Xellerate.Performance
    

    Logs database performance, such as time to execute a statement (query), or time to iterate through a result set to get data/metadata.

    oracle.iam.platform.auth
    

    Logs events for the authentication handling feature.

    oracle.iam.platform.authz
    oracle.iam.authzpolicydefn
    

    Logs events for the feature that handles authorization policies.

    oracle.iam.sod
    Xellerate.SoD
    

    Logs events related to SoD (Segregation of Duties).

    oracle.jps
    

    Logger for the embedded Oracle Entitlements Server MicroSM engine. Note that the log file is created in the OIM_ORACLE_HOME folder named as Managed Server name-microsm.log (for example, OIMServer1-microsm.log).

    Xellerate.Entitlement
    

    Provides logging for entitlement operations used for provisioning entitlements.

    oracle.iam.conf
    

    Logs events related to the system configuration services feature that includes handling system properties.

    oracle.iam.transUI
    

    Logs events related to the transitional UI feature that handles initiation of legacy APIs from the 11g code. This includes operations such as initiation of provisioning during user creation, and so on.

    Xellerate.AccountManagement
    

    Provides logging in legacy user operations APIs.

    Xellerate.Server
    

    Provides logging in data objects.

    Xellerate.ResourceManagement
    Xellerate.ObjectManagement
    

    Provides logging for resource object operations.

    Xellerate.Workflow
    

    Provides logging for provisioning process operations.

    Xellerate.WebApp
    

    Provides logging for the transitional UI operations.

    Xellerate.Adapters
    

    Provides logging for the adapter factory.

    Xellerate.JavaClient
    

    Provides logging for client-side data objects.

    Xellerate.Policies
    

    Provides logging for data objects related to access policies.

    Xellerate.Rules
    

    Provides logging for data objects related to rules.

    Xellerate.APIs
    

    Provides logging for legacy public APIs.

    Xellerate.JMS
    

    Provides logging for JMS operations where messages are produced.

    Xellerate.RemoteManager
    

    Provides logging in remote manager.

    Xellerate.Auditor
    

    Provides logging in audit framework.

    Xellerate.Attestation
    

    Provides logging in the attestation UI and operations.

    Xellerate.GC.StartUp
    Xellerate.GC.ProviderRegistration
    Xellerate.GC.ImageGeneration
    Xellerate.GC.FrameworkProvisioning
    Xellerate.GC.Provider.ProvisioningFormat
    Xellerate.GC.Provider.ProvisioningTransport 
    Xellerate.GC.FrameworkReconciliation Xellerate.GC.Provider.Reconciliation
    Format
    Xellerate.GC.Provider.Validation
    Xellerate.GC.Provider.Transformation
    Xellerate.GC.Model 
    Xellerate.GC.Server
    

    Provides logging for the Generic Technology Connector (GTC).

    oracle.iam.connectors.icfcommon
    

    Provides logging for connector framework.


  3. Define the level attribute for the <logger> element. See the example at the beginning of this section.

  4. Add one or more <handler> elements to the <logger> element.

  5. When you are finished editing both the <loggers> and <log_handlers> sections of logging.xml, save the file.

  6. Restart the application server for the changes to take effect.

20.1.5 Sample ODL Log Output

The following ODL log excerpt illustrates the kind of output you can expect.

<Jun 15, 2010 2:01:20 AM IST> <Error> <oracle.iam.platform.authz.impl>
<IAM-1010032> 
<No OES Policy found for the given Action.>
<Jun 15, 2010 2:02:02 AM IST> <Warning> <oracle.iam.platform.canonic.agentry>
<IAM-0091108> <readme.txt is not a valid connector resource file.>
<Jun 15, 2010 2:02:52 AM IST> <Error> <oracle.iam.configservice.impl>
<IAM-3020003> <The attribute User Type does not exist!>

For information about managing and interpreting log output, see "Managing Log Files and Diagnostic Data" in the Oracle Fusion Middleware Administrator's Guide.

20.2 Logging in Oracle Identity Manager By Using log4j

Apache log4j is used with third-party applications, such as Nexaweb for Deployment Manager and Workflow Designer, and OSCache for caching. The location of the log4j configuration file is:

OIM_HOME/config/log.properties

Logging in Oracle Identity Manager by using log4j is described in the following sections:

20.2.1 Log Levels

Table 20-3 lists the log levels for log4j:

Table 20-3 Log Levels for log4j

Log Level Description

DEBUG

The DEBUG level designates fine-grained informational events that are useful to debug an application.

INFO

The INFO level designates informational messages that highlight the progress of the application at coarse-grained level.

WARN

The WARN level designates potentially harmful situations.

ERROR

The ERROR level designates error events that might allow the application to continue running.

ALL

The ALL level has the lowest possible rank and is intended to turn on all logging.

OFF

The OFF level has the highest possible rank and is intended to turn off logging.


20.2.2 Loggers

The loggers for the third-party applications used are:

  • com.nexaweb.server for Nexaweb

  • com.opensymphony.oscache for OSCache

20.2.3 Configuring and Enabling Logging

Any of the log levels can be used for the third-party applications as follows:

log4j.logger.com.nexaweb.server=WARN
log4j.logger.com.opensymphony.oscache=ERROR

20.3 Setting Warning State

To set the Oracle Identity Manager server warning state:

  1. Set the re-delivery limit on all OIM JMS queues to 1. To do so:

    1. Login to the WebLogic Administration Console as the administrative user.

    2. Click JMS Modules on the Home page.

    3. Click OIMJMSModule.

    4. Click Lock & Edit.

    5. For each of the queues, click the queue, and then click the Delivery Failure tab. Change the Redelivery Limit value from -1 to 1, and then click Save.

    6. Make sure you have performed steps 1.d and 1.e for all the queues under OIMJMSModule.

    7. Release the configuration and restart Oracle Identity Manager.

      This re-delivery is not applicable for existing messages. When the server is restarted, wait for all the good messages to be processed. After that, all the bad messages must be purged.

  2. To purge all bad messages:

    1. Login to the WebLogic Administration Console as the administrative user.

    2. Click JMS Servers on the home page.

    3. Navigate to OIMJMSServer, Monitoring, Active Destinations.

    4. Select the queues that contain messages. Click Consumption, Pause.

    5. Delete the messages, as described in the following URL:

      http://docs.oracle.com/cd/E12840_01/wls/docs103/ConsoleHelp/taskhelp/jms_modules/queues/ManageQueues.html

    6. After messages are deleted, resume the consumption that has been paused in step 2.d.

  3. Restart Oracle Identity Manager.