Logging is the mechanism by which components write messages to a file. OAM administrators can use the logging mechanism to capture critical component events. Configuring logging and locating log files are the focus of this chapter. Diagnosing problems using the information in log files is outside the scope of this manual.
This chapter includes the following topics:
Oracle Access Manager 11g components use the same logging infrastructure and guidelines as any other component in Oracle Fusion Middleware 11g. This is accomplished by using the package java.util.logging, which is standard and available in all Java environments. The logging system writes output to flat files only. Logging to an Oracle Database instance is not supported.
Log messages are used for problem diagnosis. The logging infrastructure records messages from OAM components. The administrator controls the amount of information that is logged in a message by specifying log levels for each OAM component for which a logger is defined.
Note:
Generally, you enable logging to produce files that you send to Oracle Technical Support for problem diagnosis. Documentation for log messages is not available. In some cases, you might be able to diagnose problems on your own by reading log files.By default, the log level for all OAM components is the Notification level. Logging at the Error level produces a small amount of output while other log levels can result in voluminous logging output, which can impact OAM performance. In production environments, logging is usually either disabled or the log level is set to a level that results in a small volume of logging output (the error level, for example).
Oracle Access Manager uses the WebLogic container's logging defaults:
Logging File: DOMAIN_HOME/servers/SERVER-NAME/logs/SERVER-NAME-diagnostics.log
Logging Configuration File: Provides logging level and other configuration information for logging. This file is stored in the following path: DOMAIN_HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml
The following events are logged automatically:
OAM Server events (managed run-time servers)
OAM Administrative events (these are generated for configuration changes made using the Administration Console)
See Also:
Logging information in the Oracle Fusion Middleware Application Security GuideEach OAM component is associated with its own logger name, as listed in the following tables:
Table 13-1 OAM Server-Side Components
| Component Name | OAM Logger Name |
|---|---|
|
Protocol Binding |
oracle.oam.binding |
|
SSO Controller |
oracle.oam.controller.sso |
|
OAM Proxy |
oracle.oam.proxy.oam |
|
OSSO Proxy |
oracle.oam.proxy.osso |
|
Credential Collector |
oracle.oam.credcollector |
|
Remote Registration of Partners |
oracle.oam.engine.remotereg |
|
Admin-Console |
oracle.oam.admin.console |
|
Admin-Service Config |
oracle.oam.admin.service.config |
|
Diagnostics and Monitoring |
oracle.oam.diag |
Table 13-2 OAM Shared-Service Engine Components
| Component Name | OAM Logger Name |
|---|---|
|
Authentication Engine |
oracle.oam.engine.authn |
|
Policy Service Engine |
oracle.oam.engine.policy |
|
Session Management Engine |
oracle.oam.engine.session |
|
Token Engine |
oracle.oam.engine.token |
|
SSO Engine |
oracle.oam.engine.sso |
|
PartnerTrustMetadata Engine |
oracle.oam.engine.ptmetadata |
|
Authorization Engine |
oracle.oam.engine.authz |
Example 13-1 illustrates the configuration of a logger and a log handler in the file logging.xml.
See Also:
Logging information in the Oracle Fusion Middleware Application Security GuideExample 13-1 Configuring Loggers and Log Handlers
<logging_configuration>
<log_handlers>
<log_handler name='oam-handler' class='oracle.core.ojdl.logging.
ODLHandlerFactory'>
<property name='path' value='oam/diagnostic'/>
<property name='maxFileSize' value='10485760'/>
<property name='maxLogSize' value='104857600'/>
</log_handler>
</log_handlers>
<loggers>
<logger name='oracle.security.am' level='NOTIFICATION:1'>
<handler name='oam-handler'/>
...
</logger>
</loggers>
</logging_configuration>
See Also:
For more information about Java EE application logging, see Appendix I, section I.1.1, in Oracle Fusion Middleware Application Security Guide.The amount of data output by a logger is controlled by its level; the higher the level, the more information is logged. The level of a logger is specified with the element <logger> in the file logging.xml with the following format:
<logger name="loggerName" level="notifLevel"/>
where loggerName is a logger name (see Table 13-1, Table 13-2, and Table 13-3), and notifLevel is either an ODL message level or a Java message level.
Table 13-4 shows the correspondence between ODL message levels and Java message levels, in increasing level order:
Table 13-4 Mapping of ODL to Java Levels
| ODL Message Level | Java Message Level |
|---|---|
|
INCIDENT_ERROR:1 |
SEVERE.intValue()+100 |
|
ERROR:1 |
SEVERE (logs exceptions) |
|
WARNING:1 |
WARNING (logs exceptions) |
|
NOTIFICATION:1 |
INFO (default) |
|
NOTIFICATION:16 |
CONFIG |
|
NOTIFICATION:32 |
INFO and CONFIG |
|
TRACE:1 |
FINE (occasionally recommended in production environments) |
|
TRACE:16 |
FINER (not recommended in production environments) |
|
TRACE:32 |
FINEST (not recommended in production environments) |
Any other Java level value not listed above (that is, one outside the interval [SEVERE.intValue()+100 - FINEST] is mapped to the ODL level UNKNOWN.
There is no graphical user interface available to change logger levels; only WLST commands can be used. This section provides the following topics:
Administrators can use custom WLST commands for OAM to change OAM logger settings as described in the following procedure. Your deployment and choices will be different.
Note:
Use the WLST commandhelp("fmw diagnostics").To modify the OAM logger level
Confirm that the OAM Server is running.
Acquire the custom WLST script for OAM. For example:
<ORACLE_HOME>/common/bin/wlst.sh
Connect to the WebLogic Server and log in as the WebLogic administrator. For example:
sh wlst.sh wls:/offline> connect adminID password
List available OAM loggers for the OAM Server. For example:
wls:/base_domain/serverConfig> listLoggers(pattern="oracle.oam.*",target="oam_ server1")
Here pattern= represents the oam.controller component and target= represents the desired OAM Server as it was specified during registration.
View the list of OAM loggers associated with this OAM Server. For example:
Logger | Level --------------------------------------------+----------------- oracle.oam | <Inherited> oracle.oam.admin.foundation.configuration | <Inherited> oracle.oam.agent-default | <Inherited> oracle.oam.audit | <Inherited> oracle.oam.binding | <Inherited> oracle.oam.commonutil | <Inherited> oracle.oam.config | <Inherited> oracle.oam.controller | <Inherited> oracle.oam.default | <Inherited> oracle.oam.diagnostic | <Inherited> oracle.oam.engine.authn | <Inherited> oracle.oam.engine.authz | <Inherited> oracle.oam.engine.policy | <Inherited> oracle.oam.foundation.access | <Inherited> oracle.oam.idm | <Inherited> oracle.oam.idm | <Inherited> oracle.oam.idm | <Inherited> oracle.oam.user.identity.provider | <Inherited>
Modify the log level based on your requirements. For example, this sequence changes the log level of the oam.controller to TRACE:32 with no persistence:
wls:/base_domain/serverConfig> domainRuntime() wls:/base_domain/domainRuntime> setLogLevel(logger="oracle.oam.controller", level="TRACE:32", persist="0", target="oam_server1")
Repeat step 4 to list the loggers again and verify the log level change. For example:
wls:/base_domain/serverConfig> listLoggers(pattern="oracle.oam.*",target="oam_ server1")
Logger | Level --------------------------------------------+----------------- oracle.oam | <Inherited> oracle.oam.admin.foundation.configuration | <Inherited> oracle.oam.agent-default | <Inherited> oracle.oam.audit | <Inherited> oracle.oam.binding | <Inherited> oracle.oam.commonutil | <Inherited> oracle.oam.config | <Inherited> oracle.oam.controller | <Inherited> oracle.oam.default | <Inherited> oracle.oam.diagnostic | <Inherited> oracle.oam.engine.authn | <Inherited> oracle.oam.engine.authz | <Inherited> oracle.oam.engine.policy | <Inherited> oracle.oam.foundation.access | <Inherited> oracle.oam.idm | <Inherited> oracle.oam.idm | <Inherited> oracle.oam.idm | <Inherited> oracle.oam.user.identity.provider | <Inherited>
Verify the generated log file to confirm the controller is logged at the TRACE:32 level:
DOMAIN_HOME/server/SERVER_INSTNCE_NAME/logs/
Proceed to "Validating Run-time Event Logging Configuration".
Administrators can use the following procedure to specify a log file path and necessary attributes. Your deployment and choices might be different.
Note:
Use the WLST commandhelp("fmw diagnostics") to get more information.Skip steps 1 through 3 if the following items are true:
The OAM Server is running
You have the WLST script
You have connected to the server and logged in
To modify the OAM logger, level, and log handler
Confirm that the OAM Server is running.
Acquire the WLST script. For example:
<ORACLE_HOME>/common/bin/wlst.sh
Connect to the WebLogic Server and log in as the WebLogic Administrator. For example:
sh wlst.sh wls:/offline> connect
Add an OAM logger and level for the OAM Server. For example:
wls:/base_domain/serverConfig> domainRuntime() wls:/base_domain/domainRuntime> setLogLevel(logger="oracle.oam", level="WARNING", persist="0", target="oam_server1")
Here <<<???>>> represents <<<???>>> and target="oam_server1 represents the desired OAM Server.
Add a custom log handler and associate it with the OAM logger. For example:
wls:/base_domain/domainRuntime> configureLogHandler(name="oam-log-handler",
target="oam_server1", rotationFrequency="daily", retentionPeriod="week", path="${domain.home}/oamlogs" , maxFileSize ="10485760", maxLogSize = "104857600", addHandler="true", handlerType="oracle.core.ojdl.logging
.ODLHandlerFactory", addToLogger="oracle.oam")
wls:/base_domain/domainRuntime>configureLogHandler(name="oam-log-handler",
addProperty="true", propertyName="supplementalAttributes", propertyValue=
"OAM.USER, OAM.COMPONENT", target="oam_server1")
Verify all the OAM logs appear in the DOMAIN_HOME/oamlogs directory:
DOMAIN_HOME/oamlogs/
You can use the following procedure to test your run-time event logging configuration.
Configure logging using WLST commands as described in this chapter.
Ensure the Agents and Servers are running.
Configure an application domain to protect the resource as described in Chapter 9, "Managing Policies to Protect Resources and Enable SSO".
To validate run-time event logging
In a browser, enter the URL to a protected resource and sign in using an invalid credential.
Sign in again using the proper credential.
On the physical server, verify all the OAM logs appear in:
DOMAIN_HOME/oamlogs/
Open the log file and look for the last entries to confirm authentication failure and success, respectively.