23 Logging Webgate Event Messages

Each Webgate instance (both 10g and 11g Webgates) can write information about its processes and states to a log file. The logs can be configured to provide information at various levels of granularity. For example, you can record errors, errors plus state information, or errors, states, and other information to the level of a debug trace. You can also eliminate sensitive information from the logs.

Note:

Unless explicitly stated, all information in this section applies equally to 10g and 11g Webgates. For instance, the location of the log configuration, oblog_config_wg.xml, has changed for 11g while the content of the file and most other specifics have not changed.

About Logging, Log Levels, and Log Output

The logging feature enables you to analyze system performance and health, and to troubleshoot issues.

You can configure logging for individual Webgate instances of the following components:

10g Webgates

11g Webgates

Custom Access Clients (Access Manager SDK)

You can configure different logging levels for different functional areas of a component instance. For example, you can capture debug data for LDAP activity while recording only error-level data for all other component activity. You can also record the time taken for each request that a component processes, and you can send different levels of log data to different destinations. For example, you can send error information to a file and all other log data to the system log.

Securing Sensitive Information: Oracle Access Manager handles sensitive information about users. On some sites, this includes user password, date of birth, a social security number, security questions and answers for lost password requests. Sensitive data on your site might include a security number or other information you want to secure. At certain logging levels, sensitive information might be captured. Today, you can filter sensitive information out of log files, as described in "Filtering Sensitive Attributes".

About Log Levels

A logging level determines the amount of data that is written to the log data file. Each logging level is cumulative, that is, each level contains all the data generated by the higher levels. For example, Error logs contain all the data generated by the Fatal logs, plus the events that are specific to the Error category.

Records critical errors. Generally, these events can cause the component to exit.

In the event of a system failure, Fatal-level messages are always flushed to the log file.

LOGLEVEL_ ERROR

> 960

Records events that may require corrective action, for example, a component is unavailable. Error logs can also be generated for transient or self-correcting problems, for example, failure to connect to another component.

LOGLEVEL_ WARNING

> 1200

Records issues that may lead to an error or require corrective action in the future.

LOGLEVEL_ INFO

> 400

Records completed actions or the current state of a component, for example, the component is initializing.

LOGLEVEL_ DEBUG1

> 400

Records debugging information. Typically, the information at this level is only meaningful to a developer.

LOGLEVEL_ DEBUG2

> 100

Records advanced debugging information. This level augments the Debug1 log level. Typically, the information at this level is only meaningful to a developer.

LOGLEVEL_ DEBUG3

> 900

Records a large amount of debugging information or data pertaining to an expensive section of the code. This level is useful for debugging a tight loop or a performance-sensitive function. Typically, the information at this log level is only meaningful to a developer.

These logs can contain sensitive information.

LOGLEVEL_ TRACE

> 900 Oracle Access Manager API

> 150 third-party API

This log level is used to trace code path execution or to capture performance metrics. This information is captured at the entry and exit points for each component function. Typically, the information at this log level is only meaningful to a developer.

These logs can contain sensitive information.

LOGLEVEL_ ALL

> 5000

This level includes all the events and states from all other levels.

Compound Lists: You can collect log data from non-adjacent levels and send different levels of log data to different destinations. For example, you can send the Fatal logs to the system log, and write Error logs to a file. See "The Second Compound List and Log Handlers" for details.

Threshold: You configure a global cutoff, or threshold, for logging on the LOG_THRESHOLD_LEVEL parameter in the log configuration file. By default, if a configured level for a log-handler exceeds the cutoff, the log data is not collected. Note that logs can fail to be written despite the configured level because the LOG_THRESHOLD_LEVEL parameter takes precedence over the level configured in the log-handler. Only the MODULE_CONFIG section of the log configuration file overrides the global threshold. See "The Simple List and Logging Threshold" for details.

About Log Output

Each line of the log output file follows a particular structure. A line starts with a date and time stamp, followed by the thread that is processing the request, the name of the function or module being logged, and the log level.

The following is a snapshot of the left-most columns of the log output file:

The two columns to the right of the log level are internal code references, and can be ignored. The following is an example of these columns:

0x00000205 ldap_connection_mngr.cpp:212

To the right of the internal code reference columns, you see the log message that is associated with this log level, for example, "Function called" or "Function returned," followed by the name of the function, as illustrated in the following example:

"Function called" _CallName^ldap_init

The log message and function name can be followed by additional information, for example, the duration of the process, the address space where the function is running, or state information, as illustrated in the following examples:

Log Configuration File Paths and Names

By default, Webgate logging is enabled and oblogs are generated in the Oracle HTTP Server (OHS) instance diagnostics directory: instance1/diagnostics/logs/OHS/ohs1/.

Each Webgate instance includes a log configuration file (oblog_config_wg.xml) where you can define what type of data is recorded in the log output. A log configuration file is distinct from the log output file. For details on log output files, see "About Log Output".

The oblog_config_wg.xml file is updated when you edit to configure Webgate logging. For example, by setting a new log threshold level, changing a log file name, or filtering logs related to some modules and so on.

11g Webgates: Webgate/Oracle_Home under webgate/ohs/config and Instance_Home/webgate/config (the later to be used when configuring logging).

The same oblog_config_wg.xml file is copied to the Webgate instance directory when the Webgate instance is created. In Instance_Home, this file is located at webgate/config.

Note:

Do not change the path to this file. If you install more than one instance, a log configuration file is installed for each instance. When configuring logging, use oblog_config_wg.xml under Instance_Home should be updated.

After installation, oblog_config_wg.xml and oblog_config_wg_original.xml both contain comments to help guide your editing.

Table 23-2 lists the names of the log configuration files. Do not change the names.

Table 23-2 Log Configuration File Names for Components

Component

Log Configuration FIle Name

Webgate

oblog_config_wg.xml

Access Manager SDK (custom Access Client)

oblog_config.xml

Important:

Do not change the default path or name for any logging configuration file.

The oblog_config_wg.xml file can be edited using any text editor as long as you ensure that after the update the file is still valid XML. After updates to the file, changes will take affect in about 60 seconds.

Log Configuration File Contents

The log configuration file controls items such as the following:

What is logged for that component

Where the data is sent

In certain cases, the size of the write buffer used for the log

Log file rotation intervals

The configuration file contains XML statements that you can edit in a text editor.

When Changes to the File Take Effect

A watcher thread picks up changes to the log configuration file every 60 seconds and ensures that changes take effect. It is unnecessary to restart the server

About Comments in the Log File

Each default log configuration file contains comments that are intended to assist with editing the file.

See Also:

The log configuration file on your system.

The commented default configuration file is shown here:

Comments can span one or multiple lines. Comments look similar to the following:

<!--NetPoint Logging Configuration File -->
<!-- -->
<!--Changes to this file will be automatically taken into effect -->
<!--in one minute. This does not require any server restart. -->

About Directing Log Output to a File or the System File

To send log output to a destination, you configure a log writer. A log writer can send log output to one, none, or both of the following:

A log file.

This file resides under the root installation directory of the component.

The system file of the host for the component.

If more than one component resides on the same host, all components send data to the system log file on that host.

You can send logs of a particular level, or logs of different levels, to more than one type of log writer. For instance, you can send Fatal data to the system log, and send Trace data to a file. Or, you can send Fatal data to both the system log and a file.

Sends data to the system log file for the computer that hosts the component being logged. Typically, the system log file contains event information from multiple applications and the host operating system.

For Windows, this is the application log file located at My Computer, Manage, Event Viewer, Application.

For UNIX platforms, the name and location of the system log file can vary according to the computer and the preferences of the system administrator. Consult the administrator of the computer for the file location.

The default log configuration file sends Fatal, Error, and Warning messages to the system log file.

FileLogWriter

This writer is recommended when you want to save log data for an OAM Server or other single-process application on a disk file.

The FileLogWriter opens the log file and holds it open for disk writes until the approximate file size limit or file rotation interval has been reached. Oracle does not recommend this log writer for situations where more than one process needs to write to the same log file. For these situations, use the MPFileLogWriter.

MPFileLogWriter

This writer resembles the FileLogWriter, except that it opens and closes the log file each time it writes data to the file. This enables multiple processes to write to the file in turn. However, this practice can slow performance substantially.

Oracle recommends using MPFileLogWriter only when FileLogWriter fails to record logging data from some of the processes associated with a multi-process application, for example, an Access Client installed on a multi-process Web server (such as Apache) or the Solaris version of the iPlanet Web server.

Structure and Parameters of the Log Configuration File

The log configuration file conforms to a standard format. You can edit parameters and add or subtract sections known as log-handler definitions, but do not change the underlying format of the log configuration file.

Note: Ensure that LOG_THRESHOLD_LEVEL and LOG_SECURITY_THRESHOLD_LEVEL are the same or are consistent with one another. For example, if LOG_THRESHOLD_LEVEL is set to LOGLEVEL_TRACE while LOG_SECURITY_THRESHOLD_LEVEL is set at LOGLEVEL_WARNING, then secure logging applies to LOGLEVEL_WARNING and above but does not apply to LOGLEVEL_TRACE.

LOG_SECURITY_ESCAPE_CHARS

Configure escape sequence characters used to avoid additional information being overwritten due to the secure logging mechanism. Use a comma separated list.

Default value: ),]

Possible Values: Characters only

Note: Default values are recommended. Configuring inappropriate characters may lead to sensitive information being unmasked.

LOG_SECURITY_MASK_LENGTH

Specifies the default masking length if none is specified in FILTER_LIST.

The Second Compound List and Log Handlers

After the simple list containing global settings, and within the start and end tags for the initial compound list, you specify an additional compound list. This compound list contains log-handler definitions. The start and end tags for this list are as follows:

In the start tag for the compound list, the xmlns parameter indicates the relevant XML name space.

Also in the start tag, you specify the name of the list on the ListName parameter.

Typically, the name of this list is LOG_CONFIG.

Between the start and end tags for the compound list for the log-handler, you specify one or more ValNameList elements. Each ValNameList element contains the definition for a log-handler. Each instance of this element begins and ends as follows:

The opening tag sets the relevant XML name space on the xmlns parameter.

The opening tag also sets a name for the log-handler on the ListName parameter.

Within the opening and closing ValNameList tags, you configure the log-handler. A log-handler definition contains three mandatory NameValPair elements:

The first mandatory NameValPair element defines the logging level for the log-handler.

This element contains the statement ParamName="LOG_LEVEL", whose value is a reserved name in Table 23-1, as follows:

<NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_FATAL" />

The second mandatory NameValPair element defines the destination for log output.

This element contains a statement ParamName="LOG_WRITER", whose value is a reserved name in Table 23-3, as follows:

<NameValPair ParamName="LOG_WRITER" Value="SysLogWriter" />

The third mandatory NameValPair element toggles this log-handler on and off.

This element contains a statement ParamName="LOG_STATUS", with a value of On or Off, as follows:

<NameValPair ParamName="LOG_STATUS" Value="On" />

Finally, within the opening and closing ValNameList tags, if you specify FileLogWriter or MPFileLogWriter as the log writer, you can add none, some, or all of the following. See Table 23-7 for details:

A destination file name, as follows:

<NameValPair ParamName="FILE_NAME" Value="oblog.log" />

A buffer size, as follows:

<NameValPair ParamName="BUFFER_SIZE" Value="65535" />

A a file size that determines when a new log file is generated, as follows:

<NameValPair ParamName="MAX_ROTATION_SIZE" Value="52428800" />

A time in minutes that determines the interval at which a new log file is generated, as follows:

<NameValPair ParamName="MAX_ROTATION_TIME" Value="86400" />

The List for Per-Module Logging

After the end tag for the compound list that delimits the log-handlers, and before the end tag for the initial compound list, you can add per-module logging parameters.

The Filter List

After the per-module logging parameters a filter list identifies sensitive information that you might want to filter out of the log file. For example, passwords and responses for lost password management are sensitive information that you might want to filter out of the log file.

Each name value pair associated with the FILTER_LIST parameter provides the name of a word or phrase to be checked before the log is written and the corresponding masking length for that word or phrase. During logging, the value of the word or phrase is masked and omitted from the log file.

Simply put, during logging Oracle Access Manager does not recognize whether a value to be masked is an attribute or its display name or something different (plain text). Secure Logging works by searching for words or phrases added in the FILTER_LIST and then masking out any data that is followed by the occurrence of those words or phrases. For example, in the following statement:

After turning Secure Logging ON and adding “bind” in the FILTER_LIST (which is neither an attribute nor a display name), whatever follows the word in the FILTER_LIST (in this case, "bind") is masked. In this case, you would see the following in logs:

All attributes are case sensitive. For example, if you enter "password" instead of "Password" as a display name for an attribute, then "Password" is not filtered. By default, four attributes are always configured in the filter list: password, Password, response, and Response.

The default masking length, 40, is specified for each of the four default attributes. The default mask length can be altered for the default attributes if needed. If you add other attributes to the filter list, you might need a larger mask length (300, for example).

When you add another attribute to the filter list, you must include the display name as well as the attribute name in the directory server.

About XML Element Order

When using XML, you can specify parallel elements in a list in any order as long as the elements remain intact and within the tags that originally bracketed them. For example, the lists in Example 23-4 and Example 23-5 are equivalent:

Similarly, within a given tag, the attributes (except for the tag name, which must always be the first element within the tag brackets) can be reordered, as long as they remain intact and within the tag elements that originally bracketed them. The opening tags for a name-value list in Example 23-6 and Example 23-7 are equivalent:

Example 23-6 Opening tag for a Name/Value List

<ValNameList xmlns="http://www.example.com" ListName="LogError2Sys">

Example 23-7 Opening tag for a Name/Value List

<ValNameList ListName="LogError2Sys" xmlns="http://www.example.com">

About Activating and Suppressing Logging Levels

Several factors determine if logging is active for a particular log-handler. Table 23-5 lists these factors.

Table 23-5 Factors that Determine Whether Logging Is Active

Factor

Importance

Description

LOG_ THRESHOLD_ LEVEL

Primary

This parameter sets a cutoff for logging. Any log level that is more detailed than the threshold is suppressed. See Table 23-1 for valid log levels.

About Log Handler Precedence

You can configure up to three log-handler definitions for a single log level in a log configuration file. Three different log handlers are required to send output for a particular log level to each of the three log writers described in Table 23-3.

If you specify different LOG_STATUS settings in these log handlers, the setting in the log-handler definition closest to the physical end of the log configuration file sets the status for the other log-handler definitions of the same log level. For example, you can set LOG_STATUS to Off for the first two log handlers for the Error log level, but if LOG_STATUS is On for the third and final log handler in the configuration file, logging still occurs for all three handlers.

Mandatory Log-Handler Configuration Parameters

At minimum, each log-handler definition contains five parameters listed in Table 23-6.

Table 23-6 Mandatory Log Configuration File Parameters

Parameter

Comment

xmlns

This parameter is specified in the opening ValNameList tag.

It specifies the relevant XML namespace for the current list and is identical for all log-handler definitions in a given logging configuration file. Example:

http://www.example.com

ListName

This parameter is specified in the opening ValNameList tag. Where possible, use the default names.

When creating a new log-handler definition, select a memorable name that you cannot confuse with other log handlers. Examples:

WarningsAndAboveToSyslog sends Fatal, Error, and Warning messages to the system log file.

WarningsOnlyToFileLog128KBuffer sends messages from just the Warning level to a 128KB buffer, and hence to a disk file.

TraceOnlyToMPRotateDaily sends messages from just the Trace level to the multi-process file writer, which opens and closes the file each time it writes to disk. This file is replaced with a fresh (empty) file every day, regardless of the size of the file at the time of replacement.

This specifies the destination for log output for this log-handler. See Table 23-3 for details.

The default log configuration file sends output to both the system log and the log data file for the component doing the logging.

LOG_STATUS

This parameter turns the log handler on or off.

If you specify FileLogWriter or MPFileLogWriter as the value for the LOG_WRITER parameter, the four parameters in Table 23-7 are relevant.

Table 23-7 Log Data File Configuration Parameters

Parameter

Description

Default

FILE_ NAME

Mandatory. Used only for the FileLogWriter or MPFileLogWriter. It is the name and location of the file where log data is written.

You can prepend an absolute path to the file name to store it somewhere other than the default location, which is:

Webgate_install_dir\oblix\logs

Where component_install_dir is the root installation directory for the component whose system events you are logging.

When you create more than one log-handler definition that sends output to FileLogWriter or MPFileLogWriter, provide unique file names so that multiple handlers do not write to the same file. This caution does not apply to log handlers accessing the SysLogWriter.

oblog.log

BUFFER_SIZE

Optional. This is the size of the buffer, in bytes, for logged data as it is being written to the log file.

If you set the buffer value to 0 or a negative number, the default value is used. To write to the log file immediately, without buffering, set the value to a small number, for example, 5. Oracle recommends that you set a small buffer size in situations where there are system failures.

65535

(64KB)

MAX_ ROTATION_ SIZE

Optional. When the log file reaches this size (in bytes), a time stamp is appended to the file name, for example "oblog.log" becomes "oblog.log1081303126." New data is written to the file with the original name.

52428800

(512KB)

MAX_ ROTATION_ TIME

Optional. A time interval, in seconds, when the log file is renamed, whether or not it has reached the maximum rotation size.

If the rotation time determines when the file is rotated, the numbers appended to the log files differ by the number of seconds in the rotation interval. For example, "oblog.log.1081389526" and "oblog.log.1081303126" differ by 84,600, which is the number of seconds in 24 hours. This is the rotation interval set in the log configuration file.

86400

(1 day, in seconds)

Settings in the Default Log Configuration File

As installed with each component, the log configuration file activates only the highest three levels (Fatal, Error, and Warning) and directs all log output to the system log.

On Windows, you can view the system log for the computer that hosts the component you are logging by navigating to My Computer, Manage, Event Viewer, Application. System event entries for the components being logged are interspersed among the system events for the operating system and applications other than Oracle Access Manager.

For Solaris and Linux environments, the location of the system log is recorded in a system configuration file whose particulars can vary from computer to computer. For the name and location of this system file or the system log, consult the owner of the computer that hosts the component whose system log you want to examine.

The first, named LogFatal2Sys, sets the logging level to Fatal and sets LOG_STATUS to On.

The threshold level is Warning, which is more fine-grained than Fatal, so this definition is in effect. The log output is written to the system log, as specified by the LOG_WRITER parameter.

The LogError2Sys log-handler definition sends Error level messages to the system log.

Error is located before the current threshold level (Warning), so this definition is in effect.

The LogWarning2Sys definition sends Warning level output to the system log.

Like the two previous log-handler definitions, it is not overridden by the current LOG_THRESHOLD_LEVEL parameter.

LogAll2File, the final log-handler definition, appears to send output from all log levels to a disk file named oblog.log.

The LOG_THRESHOLD_LEVEL parameter is set to Warning, so only the output from the Fatal, Error, and Warning levels are recorded in this log data file. Since output from LogAll2File goes to the FileLogWriter, the parameters governing file name, buffer size, rotation size, and rotation interval all take effect.

Configuring Different Threshold Levels for Different Types of Data

When diagnosing a problem, you may not want detailed logs for every operation that a component performs. For example, to diagnose slow response times for requests that an Identity Server submits to its directory, you would want detailed information on LDAP operations and fewer details about other types of operations.

As of release 10.1.4.2, you can configure per-module or per-function threshold levels in the log configuration file, so that Oracle Access Manager generates detailed logs for some components while generating concise logs, or no logs, for others.

You configure per-module logging thresholds in a MODULE_CONFIG section in the oblog_config_wg.xml file. The MODULE_CONFIG section overrides the global default that you specify on the LOG_THRESHOLD_LEVEL in the simple list section of this file.

In addition to the global threshold, the configuration file can contain a ValNameList that defines function- or module-specific log thresholds. The name of this list is always MODULE_CONFIG. Only one instance of this list is permitted in the log configuration file, and the information in the list applies to all log writers defined in the file. As of release 10.1.4.2, the default log configuration file contains a commented sample of the MODULE_CONFIG list.

Each item in the MODULE_CONFIG list sets a logging level for a module, as shown in the following example:

The Value parameter sets the logging threshold for the module that you specify as a value for the ParamName parameter.

Table 23-1 lists the permissible values for the Value parameter. In addition to these values, you can specify the value ON to enable logging for the module and a value of OFF to disable logging for the specific module.

Location of the Per-Module Logging Section in the Log Configuration File

You add the per-module logging threshold section near the end of the log configuration file, after the closing tag for the compound list for the log-handlers and before the closing tag for the first compound list in the file.

Place this list after the end tag for the compound list that contains the log handler definitions. If there are comments immediately after this end tag, place the list after the comments.

Between the opening and closing tags of the new ValNameList element, configure one or more NameValPair elements.

This element contains a ParamName parameter and a Value parameter. See Table 23-8 for the modules that you can supply on the ParamName parameter. See Table 23-1 for values, or you can specify a value of On or Off. The following is an example:

<NameValPair ParamName="LDAP" Value="LOGLEVEL_TRACE"></NameValPair>

You can specify multiple ValNamePair elements within the ValNameList.

A complete per-module logging threshold section is illustrated in bold in the following example:

Filtering Sensitive Attributes

As described earlier, you can activate secure logging and expand the default filter list to mask sensitive information from the log file.

When you add another attribute to the filter list, you must include the display name as well as the attribute name in the directory server. The following procedure describes how to perform this task. In this example, you are instructed to filter the user's home phone number: display name Home Phone; attribute name homePhone. However, you can filter the attribute of your choice.

Note:

Each value added to FILTER_LIST increases the runtime cost of using Secure Logging.

Oracle recommends that you optimize the use of FILTER_LIST to reduce the runtime cost. For example, rather than adding two ParamName variations ("User Password" and "userPassword"), you could use only one. Using "Password" as the ParamName masks values for "User Password", "userPassword", and other words that end with "Password". Also, instead of including both "Home Phone" and "homePhone" in FILTER_LIST, you could use only "Phone".