You can enable logging to help troubleshoot problems or test rules. In rule logging, rows are written to the VR_RULE_LOGS table.
This appendix describes how to configure rule logging in OAAM. It contains the following sections:
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. The information shown in the Session Details page is based on the rule logs that are written when the rules execute.
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.
Detailed rule logging 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 that amount of time 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.
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.
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.
The rule was tested and the conditions were satisfied, so the rule was triggered.
This status is not used currently.
An internal error occurred while testing this rule. Check the logs for more details.
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
You should never have a rule log with this status.
Table K-1 shows the rule logging configuration properties.
Table K-1 Rule Logging Properties
| Properties | Description |
|---|---|
|
vcrypt.tracker.rules.trace.policySet |
True/False Enables rule logging. |
|
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 |
|
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. |
|
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. |
Enable rule logging by using the Properties editor. The steps are as follows:
Log in to the OAAM Admin Console.
In the Navigation pane, double-click Properties under the Environment node. The Properties Search page is displayed.
Enter vcrypt.tracker.rules.trace.policySet in the Name field and click Search.
You should see the property in the Search Results section.
Click to select the property in the Search Results section.
In the vcrypt.tracker.rules.trace.policySet details section, enter true in the Value field.
Click Save.
A confirmation dialog is displayed.
Click OK to dismiss the dialog.
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.
In the New Property dialog, type in the property name and value.
Click Create.
Enable rule logging for a specific checkpoint by using the Properties editor. The steps are as follows:
Log in to the OAAM Admin Console.
In the Navigation pane, double-click Properties under the Environment node. The Properties Search page is displayed.
From the Properties Search page, click the New Property button or Create new Property icon.
A New Property dialog is displayed.
In the New Property dialog, type in vcrypt.tracker.rules.trace.policySet.checkpoint in the Name field.
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:
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.
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 |
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 |
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.
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 "n" in milliseconds specified, Oracle Adaptive Access Manager starts the detailed rule logging.
To enable or disable fingerprint rule logging, modify the following property using the Property editor:
vcrypt.tracker.rulelog.fingerprint.enabled=true
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
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=
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.