Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager
11g Release 1 (11.1.1)

Part Number E14568-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

L Rule and Fingerprint Logging

You can enable logging to help troubleshoot problems or test rules. In rule logging, rows are written to the VR_RULE_LOGS table.

In Oracle Adaptive Access Manager, rule logs are captured during the execution of various policies and rules at the different checkpoints (such as Pre-Authentication, Post-Authentication, and others).

Oracle Adaptive Access Manager supports two rule logging options:

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.

L.1 About Rule Logging

Rule logging records the required rule processing information so that the Administrator can monitor the required information from a user session. Rule log details are captured in the VR_RULE_LOGS table while executing various policies and rules at different checkpoints.

L.1.1 Fingerprint Rule Logging

Fingerprint rule logging records the policies and rules that were executed. 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. The fingerprint is a digest of a set of rules that were triggered. When a set of rules is triggered, a digest of the triggered rules is created and persisted in the database. The next time the same set of rules is triggered, the digest is reused and persisted so that the new session will have the same digest now for the runtime. When fingerprint logging is performed, the time required for the rule and policy execution is not captured and displays as -1 or N/A in the Session Details page. Fingerprint rule logging is enabled by default.

L.1.2 Detailed Rule Logging

Detailed rule logging captures the captures the rules that were executed and the length of time that the rule or policy took to execute. The execution time is used as a performance statistic. Detailed rule logs are created only if the execution time is more than a threshold value that you have configure. On a production machine, you want to manage the amount of time before detailed logging is enabled since increasing the amount of logging may negatively affect performance. If the details are logged about the rules (runtime) that have a long execution time, the overhead for logging is decreased.

If the runtime requires an unusual amount of time, you might want to run detailed rule logging so that you can perform further analysis on why the rule took so long to run. Fingerprinting logging does not capture the timing information. Timing is an important factor in troubleshooting the "slow" runtime. In detailed logging, by default, only log timing for the rules that triggered are logged. The untriggered rules are not logged unless you specify you want to capture the untriggered rules also. Untriggered are captured in fingerprint rule logging.

L.1.3 Status Columns in the VR_RULE_LOGS Table

The VR_RULE_LOGS table enables administrators to view the status of the rules. This information can be used for troubleshooting rules.

This status columns are explained in this section.

0 = notfired

The rule was tested but the conditions were not satisfied, so the rule was not triggered.

Rule logs are not always created for notfired status. There are properties that control whether the notfired status is shown or not.

If vcrypt.tracker.rules.trace.notTriggered is set to false, then rule logs for the notfired status are never created.

The property vcrypt.tracker.rules.trace.notTriggered.logMillis contains a threshold in milliseconds. If the rule executed in fewer milliseconds than this threshold, then the rule log will not be created.

If you want to always log notfired status rules, then set vcrypt.tracker.rules.trace.notTriggered to true and set vcrypt.tracker.rules.trace.notTriggered.logMillis to 0.

If you never want to log notfired status rules, then set vcrypt.tracker.rules.trace.notTriggered to false.

If you only want to log notfired status rules that take longer than a certain amount of time to test the conditions, then set vcrypt.tracker.rules.trace.notTriggered to true and set vcrypt.tracker.rules.trace.notTriggered.logMillis to the threshold millisecond value that you want.

1 = fired

The rule was tested and the conditions were satisfied, so the rule was triggered.

2 = override

This status is not used currently.

3 = error

An internal error occurred while testing this rule. Check the logs for more details.

Status 4-8

These columns all deals with preconditions. If the rule was not tested because preconditions were set up to exclude the device, city, state, country, or group, then the rule log will show a status that matches the precondition.

4 = deviceScoreExclude

5 = cityScoreExclude

6 = stateScoreExclude

7 = countryScoreExclude

8 = groupExclude

99 = unknown

You should never have a rule log with this status.

L.2 Rule Logging Properties

Table L-1 shows the rule logging configuration properties.

Table L-1 Rule Logging Properties

Properties Description

vcrypt.tracker.rules.trace.policySet

True/False

Enables rule logging.

vcrypt.tracker.rules.trace.policySet.checkpoint

True/False

Enables rule logging. You can specify the checkpoint in which to log the rules. The variable checkpoint corresponds to the checkpoint.

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.

vcrypt.tracker.rules.trace.policySet.min.ms

1000 (milliseconds)

Specifies when to perform rule logging. You must configure this property to enable rule logging. You can configure this property for time so that logging is performed only if the total time taken for the runtime is greater than this value. The property, as set, logs for all runtime process rules only if the total time taken is more than 1000 ms.

-1

If you are unable to see the rules log in the Session Details page with the above property value, change it to -1.

vcrypt.tracker.rules.trace.notTriggered

False

If set to true, untriggered rules are logged along with the triggered rules

vcrypt.tracker.rules.trace.notTriggered.logMillis

Narrows down which rules are logged.

If the rule execution for untriggered rules exceeds the value specified then untriggered rules are logged.

vcrypt.tracker.rulelog.detailed.minMillis

2000

Determines the minimum time required for detailed logging. You can configure rule logging such that detailed rule logs are created only if the execution time is more than a threshold. That way, details are logged against the rules (runtime) with long execution time and hence the overhead of detailed logging is reduced.

Controls threshold for the logging for rules. By default, the Session Details page does not display the trigger sources if the execution time for alerts is less than 2000 millisecond (2000 ms) since detailed logging is dependent on the execution time.

vcrypt.tracker.rulelog.fingerprint.enabled

True/False

Enables fingerprint logging.

vcrypt.tracker.rulelog.exectime.maxlimit

Determine if fingerprint or detailed logging runs. If the value is exceeded, detailed logging is performed. Both are run if the property is set to -1.


L.3 Enabling Rule Logging

Enable rule logging by using the Properties editor. The steps are as follows:

  1. Log in to the OAAM Admin Console.

  2. In the Navigation pane, double-click Properties under the Environment node. The Properties Search page is displayed.

  3. Enter vcrypt.tracker.rules.trace.policySet in the Name field and click Search.

    You should see the property in the Search Results section.

  4. Click to select the property in the Search Results section.

  5. In the vcrypt.tracker.rules.trace.policySet details section, enter true in the Value field.

  6. Click Save.

    A confirmation dialog is displayed.

  7. Click OK to dismiss the dialog.

  8. If the property does not exists, from the Properties Search page, click the New Property button or Create new Property icon.

    A New Property dialog is displayed.

  9. In the New Property dialog, type in the property name and value.

  10. Click Create.

L.4 Enabling Rule Logging for a Specific Checkpoint

Enable rule logging for a specific checkpoint by using the Properties editor. The steps are as follows:

  1. Log in to the OAAM Admin Console.

  2. In the Navigation pane, double-click Properties under the Environment node. The Properties Search page is displayed.

  3. From the Properties Search page, click the New Property button or Create new Property icon.

    A New Property dialog is displayed.

  4. In the New Property dialog, type in vcrypt.tracker.rules.trace.policySet.checkpoint in the Name field.

  5. Enter true in the Value field and click Create.

To illustrate how rule logging for checkpoints is control by property combinations, a matrix is shown below. The Post-Authentication checkpoint is used to illustrate checkpoint rule logging flow.

The flow is as follows:

  1. The Rules Engine checks for a configuration for vcrypt.tracker.rules.trace.policySet.postauth.

  2. 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.

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.

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

vcrypt.tracker.rules.trace.policySet.postauth vcrypt.tracker.rules.trace.policySet Checkpoint Rule logging enabled?

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


L.5 Enabling Logging of Untriggered Rules

To configure rule logging to log untriggered rules, use the Properties editor to set the following properties:

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

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 untriggered rules exceeds the value of vcrypt.tracker.rules.trace.notTriggered.logMillis, only then will the Rules Engine log the untriggered Rules.

The following table shows the property values that control rule logging for untriggered rules.

vcrypt.tracker.rules.trace.notTriggered vcrypt.tracker.rules.trace.notTriggered.logMillis Result

true

n

Logs the untriggered Rules that took more than "n" milliseconds. If "n" is set to a negative value, all rules are logged

false

n

None of the untriggered rules are logged


L.6 Enabling Detailed Logging

Configure the minimum time required for detailed logging so that details are logged for rules (runtimes) that have long execution times. Detailed rule logs are created only if the execution time is more than a threshold.

  1. In the Navigation tree, double-click Properties under Environment.

  2. Enter vcrypt.tracker.rulelog.detailed.minMillis in the Name field and click Search.

  3. In the Results table, select vcrypt.tracker.rulelog.detailed.minMillis.

  4. In the Details vcrypt.tracker.rulelog.detailed.minMillis section, edit the value in the Value field.

  5. Click Save.

    A confirmation dialog is displayed.

  6. Click OK to dismiss the dialog.

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

L.7 Enabling Fingerprint Rule Logging

To enable or disable fingerprint rule logging, modify the following property using the Property editor:

vcrypt.tracker.rulelog.fingerprint.enabled=true

L.8 Other Fingerprint and Detailed Logging Properties

Properties can be set for

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=

L.9 Archiving and Purging Rule Log Data

The OAAM archive and purge script will archive and purge all rule log data that is 30 days old, but you should set the value based on the customer care requirement. If the reporting database is used, then, rule logging data retention should be less than 30 days.

Table L-2 Rules and Policy Log Data Tables

Rules, Policy Log Tables Corresponding Archived Tables

VR_POLICYSET_LOGS

VR_POLICYSET_LOGS_PURGE

VR_RULE_LOGS

VR_RULE_LOGS_PURGE

VR_MODEL_LOGS

VR_MODEL_LOGS_PURGE

VR_POLICY_LOGS

VR_POLICY_LOGS_PURGE