K Rule and Fingerprint Logging

You can enable logging to help troubleshoot problems or test rules. This appendix describes how to configure rule logging in OAAM.

K.1 Introduction

In Oracle Adaptive Access Manager, you enable rule logs during the execution of various policies and rules at the different checkpoints (such as Pre-Authentication, Post-Authentication, and others) to help troubleshoot problems or test rules.

Note: In 11g, rule log fingerprinting is enabled by default.

K.2 Configuring Rule Logging

The following configuration controls rule logging:

vcrypt.tracker.rules.trace.policySet=[true|false]
vcrypt.tracker.rules.trace.policySet.<runtime string value>=[true|false]

K.2.1 Scenario

The following scenario illustrates how rule logging works>

Scenario

For profile.type.enum.postauth.name=Post-Authentication, the runtime string value is "postauth."

K.2.1.1 How It Works

In the next sections, the Post-Authentication checkpoint is used to illustrate rule logging.

The flow is as follows:

The Rules Engine checks for a configuration for vcrypt.tracker.rules.trace.policySet.postauth.
If there is no configuration for vcrypt.tracker.rules.trace.policySet.postauth, the Rules Engine checks the configuration value of vcrypt.tracker.rules.trace.policySet.

The default value for vcrypt.tracker.rules.trace.policySet is set to true.

Refer to Section K.2.1.2, "Cases" for details on value combinations that specify rule logging.

K.2.1.2 Cases

The following matrix shows an example of how value combinations control logging during a specified checkpoint.

The Post-Authentication checkpoint is used in this example.

value of vcrypt.tracker.rules.trace.policySet.postauth	value of vcrypt.tracker.rules.trace.policySet	Will Rule logging be enabled for the postauth checkpoint?
true	false	yes
true	true	yes
true	not set	yes
false	false	no
false	true	no
false	not set	no
not set	false	no
not set	true	yes
not set	not set	yes

K.2.1.3 Essential Point

If the logging configuration is explicitly set at the given checkpoint, the Rules Engine uses that value; otherwise, it uses the value of vcrypt.tracker.rules.trace.policySet.

K.2.2 Controling Which Rules Are Logged

The properties to control the logging of rules are:

vcrypt.tracker.rules.trace.notTriggered=[true|false]
vcrypt.tracker.rules.trace.notTriggered.logMillis=[millis]

K.2.2.1 How It Works

The value of vcrypt.tracker.rules.trace.notTriggered adds rules to log. If set to "true," rules that are not triggered are logged along with the triggered rules.

The value of vcrypt.tracker.rules.trace.notTriggered.logMillis narrows down which rules are logged.

If the rule execution for non-triggered rules exceeds the value of vcrypt.tracker.rules.trace.notTriggered.logMillis, only then will the Rules Engine log the non-triggered Rules.

K.2.2.2 Examples

The following table shows the property values that control what rules are logged.

vcrypt.tracker.rules.trace.notTriggered	vcrypt.tracker.rules.trace.notTriggered.logMillis	Result
true	n	Logs the non-triggered Rules that took more than "n". If "n" is set to a negative value, all Rules are logged
false	n	None of the non-triggered Rules will be logged

K.3 Detailed Rule Logging

Detailed rule logging captures the time taken at each rule level. Detailed rule logs are created only if the execution time is more than a threshhold. The details are logged about the rules (runtime) that have a long execution time and hence the overhead of detailed logging is fair.

Time taken values are performance statistics and the length of time that the rule or policy took to execute.

Note:

On a production machine, you want to manage the amount of time logging is enabled since increasing the amount of logging may negatively affect performance.

The information shown in the Session Details page is based on the rule logs that are written when the rules execute.

Detailed rule logs are governed by two properties:

#Int property determining minimum time required for detailed logging 
vcrypt.tracker.rulelog.detailed.minMillis=2000 
#Boolean property which enables the fingerprint logging. Defaults to true 
vcrypt.tracker.rulelog.fingerprint.enabled=true

If you always want detailed logs for all the sessions, adjust the time property mentioned above and that feature.

K.3.1 Enabling Detailed Rule Logging

The steps to enable detailed rule logging are:

In the Navigation tree, double-click Properties under Environment.
Enter vcrypt.tracker.rules.trace.policySet in the Name field and click Search.
In the Results table, select vcrypt.tracker.rules.trace.policySet.
In the Details vcrypt.tracker.rules.trace.policySet section, enter true in the Value field.
Click Save.

A confirmation dialog is displayed.
Click OK to dismiss the dialog.
Specify checkpoint to log rules.

K.3.2 Specifying When to Log

The steps to specify the checkpoint in which to log are:

In the Navigation tree, double-click Properties under Environment.
Click the New Property button or the Create new property icon.
Enter vcrypt.tracker.rules.trace.policySet.<checkpoint string value> in the Name field.
Enter true in the Value field and click Create.

K.3.3 Configuring Detailed Logging Threshold Time

For detailed rule logging, you can configure a threshold time value, "x," so that logging is performed only if the time taken for the rule is greater than the threshold value.

To modify the threshold time after which the rule logging should begin, follow these steps:

In the Navigation tree, double-click Properties under Environment.
Enter vcrypt.tracker.rulelog.detailed.minMillis in the Name field and click Search.
In the Results table, select vcrypt.tracker.rulelog.detailed.minMillis.
In the Details vcrypt.tracker.rulelog.detailed.minMillis section, edit the value in the Value field.
Click Save.

A confirmation dialog is displayed.
Click OK to dismiss the dialog.

If a policy takes more than "x" in milliseconds specified, Oracle Adaptive Access Manager starts the detailed rule logging.

K.3.4 Enabling Fingerprint Rule Logging

Fingerprint rule logging captures only during the time taken at the policy level. Fingerprint-based logs are a shorter version of the rule logs; they do not include alert sources and per rule time, and so on. Fingerprint based logging is done to minimize data growth and also keep the logging overhead to a minimum.

To enable or disable fingerprint rule logging, modify the following property

vcrypt.tracker.rulelog.fingerprint.enabled=true

K.3.5 Specifying Properties in Running Both Fingerprint and Detailed Logging

Properties can be set for

Running either fingerprint or detailed logging
Running both fingerprint and detailed logging and when
Fingerprint logging threshold

Specify Whether Fingerprint or Detailed Logging Runs

To set a property to determine if fingerprint or detailed logging runs, set

vcrypt.tracker.rulelog.exectime.maxlimit

If the value is exceeded, detailed logging is performed.

Specify to Include Other Limits

To include all specified properties in determining the use of both, set

vcrypt.tracker.rulelog.exectime.maxlimit=-1

Specify Not to Use Both

To specify to perform logging with both logging mechanisms (detailed and fingerprint), set

vcrypt.tracker.rulelog.logBoth

to true. The value overrides vcrypt.tracker.rulelog.exectime.maxlimit.

Configuring Fingerprint Logging Threshold Time

To modify the threshold time after which fingerprint rule logging should be used, set the following property in milliseconds:

vcrypt.tracker.rulelog.exectime.maxlimit=