B Oracle Business Rules DMS Instrumentation

Oracle Rules Engine runs as a library that an application or application component uses to work with rules. The application or component can include an application name in the configuration passed to a RuleSession constructor. With a name present, the name becomes the top level in a DMS hierarchy. This facilitates analysis of Oracle Rules Engine runtime.

In order to keep metrics for a RuleSession instance, the instance must have a name. A name for the RuleSession may be included in the configuration that is passed to the RuleSession constructor. If no name is specified and DMS is configured, then the Oracle Rules Engine generates a name.

This appendix includes the following sections:

Enabling Oracle Business Rules DMS Instrumentation
Oracle Business Rules Metrics

B.1 Enabling Oracle Business Rules DMS Instrumentation

Support for DMS instrumentation is encapsulated so that the Oracle Rules Engine uses a set of interfaces defined in oracle.rules.rl.dms. If a RuleSession is created with DMS enabled, then rl_dms.jar must be in the classpath otherwise RuleSession construction fails.

B.2 Oracle Business Rules Metrics

Oracle Business RulesDMS metrics are organized in a hierarchy that reflects the key components in a RuleSession. The path in the hierarchy to the metrics for a RuleSession is (application specified portions are in italics):

/appName/rules/rl/rule_session_name/

Under each RuleSession, there is:workingMemoryruleset/ruleset_name/rule/rule_name

where there are 1 or more rule sets. The ruleset named main is always present and 0 or more rules are shown for each ruleset. DMS Nouns are defined for rules, rule sets, working memory, rule sessions, and rl. DMS Noun Types contain DMS Sensors which contain the metrics.

B.2.1 Oracle Business Rules Rule Metrics

Table B-1 shows the Oracle Business Rules Rule metrics.

Table B-1 Oracle Business RulesRule Metrics (RLRuleType)

Metric	Description	Unit
`addActivation`	the number of activations of this rule that were added to the agenda	ops
`removeActivation`	the number of activations of this rule that were removed from the agenda.	ops
`clearActivations`	The number of activations removed by reset() or clearRule()	ops
`activations`	The number of activations of this rule currently on the agenda	ops
`fire`	The number of activations of this rule that fired	ops

The behavior of adding and removing activations from the agenda is that when a fact is updated, re-asserted, and the activation remains a valid match, the activation is removed and then added back. Thus, each sensor is incremented. This occurs because an update of fact results in two tokens flowing through the Rete network, a remove token and an add token.

If a rule is removed using the clearRule built in function, the RLRuleType instance for that rule is destroyed and any data is lost.

B.2.2 Oracle Business Rules Ruleset Metrics

Table B-2 shows the Oracle Business Rules Ruleset metrics.

Table B-2 Oracle Business Rules Ruleset Metrics (RLRulesetType)

Metric	Description	Unit
`rules`	The number of rules that are defined in this ruleset. The metrics from the RLRuleType instances for each rule in this ruleset are aggregated at the ruleset level.	ops

B.2.3 Oracle Business Rules Working Memory Metrics

Table B-3 shows the Oracle Business Rules Working Memory metrics.

Table B-3 Oracle Business Rules Working Memory Metrics (RLWorkingMemoryType)

Metric	Description	Unit
`facts`	The number of facts in working memory	ops
`assert`	The number of new fact asserts	ops
`re`-assert	The number of asserts of modified facts	ops
`retract`	The number of fact retract	ops
`resetRetracts`	The number of facts retracted by reset invocations	ops

B.2.4 Oracle Business Rules RuleSession Metrics

Table B-4 shows the Oracle Business Rules RuleSession metrics.

Table B-4 Oracle Business Rules RuleSession Metrics (RLRuleSessionType)

Metric	Description	Unit
`rulesets`	the number of rulesets that are defined in this rule session	ops
`reset`	the number of reset invocations	ops

During initialization of a RuleSession, a reset is invoked so the number of reset invocations will always be one more than invoked by the RuleSession client.

The metrics from the RLRulesetTypes and the RLRuleTypes will be aggregated at the rule session level through the DMS roll up feature. Unlike RLRuleType, instances of RLRuleSessionType are never destroyed.