clara.tools.inspect — com.github.k13labs/clara-rules 0.9.2

Tooling to inspect a rule session. The two major methods here are:

• inspect, which returns a data structure describing the session that can be used by tooling.
• explain-activations, which uses inspect and prints a human-readable description covering why each rule activation or query match occurred.

ConditionMatch clj

A structure associating a condition with the facts that matched them. The fields are: :fact - A fact propagated from this condition in a rule or query. For non-accumulator conditions, this will be the fact matched by the condition. For accumulator conditions, it will be the result of the accumulation. So, for example, if we have a condition like

[?cold <- Cold]

a ConditionMatch for this condition will have a Cold fact in its :fact field. If we have a condition like

[?min-cold <- (acc/min :temperature) :from [Cold]]

the value of :fact will be the minimum temperature returned by the accumulator.

:condition - A structure representing this condition. This is the same structure used inside the structures defining rules and queries.

:facts-accumulated (nullable) : When the condition is an accumulator condition, this will contain the individual facts over which the accumulator ran. For example, in the case above with the condition

[?min-cold <- (acc/min :temperature) :from [Cold]]

this will contain the individual Cold facts over which we accumulated, while the :fact field will contain the result of the accumulation.

explain-activations clj

(explain-activations session & {:keys [rule-filter-fn] :as options})

Prints a human-friendly explanation of why rules and queries matched in the given session. A caller my optionally pass a :rule-filter-fn, which is a predicate

(clara.tools.inspect/explain-activations session :rule-filter-fn (fn [rule] (re-find my-rule-regex (:name rule))))

inspect clj

(inspect session)

Inputs: [session]

Returns a representation of the given rule session useful to understand the state of the underlying rules.

The returned structure always includes the following keys:

• :rule-matches -- a map of rule structures to their matching explanations. Note that this only includes rule matches with corresponding logical insertions after the rules finished firing.
• :query-matches -- a map of query structures to their matching explanations.
• :condition-matches -- a map of conditions pulled from each rule to facts they match.
• :insertions -- a map of rules to a sequence of {:explanation E, :fact F} records to allow inspection of why a given fact was inserted.
• :fact->explanations -- a map of facts inserted to a sequence of maps of the form {:rule rule-structure :explanation explanation}, where each such map justifies a single insertion of the fact.

And additionally includes the following keys for operations performed after a with-full-logging call on the session:

• :unfiltered-rule-matches: A map of rule structures to their matching explanations. This includes all rule activations, regardless of whether they led to insertions or if they were ultimately retracted. This should be considered low-level information primarily useful for debugging purposes rather than application control logic, although legitimate use-cases for the latter do exist if care is taken. Patterns of insertion and retraction prior to returning to the caller are internal implementation details of Clara unless explicitly controlled by the user.

Users may inspect the entire structure for troubleshooting or explore it for specific cases. For instance, the following code snippet could look at all matches for some example rule:

(defrule example-rule ... )

...

(get-in (inspect example-session) [:rule-matches example-rule])

...

The above segment will return matches for the rule in question.

InspectionSchema clj

map->Explanation clj

(map->Explanation m26316)

Factory function for class Explanation, taking a map of keywords to field values, but not much slower than ->x like the clojure.core version. (performance is fixed in Clojure 1.7, so this should eventually be removed.)

node-fn-name->production-name clj

(node-fn-name->production-name session node-fn)

A helper function for retrieving the name or names of rules that a generated function belongs to.

'session' - a LocalSession from which a function was retrieved 'node-fn' - supports the following types:

1. String - expected to be in the format '<namespace>/<Node abbreviation><NodeId><Function abbreviation>'. Expected use-case for string would be in the event that a user copy pasted this function identifier from an external tool, ex. a jvm profiler
2. Symbol - expected to be in the format '<namespace>/<Node abbreviation><NodeId><Function abbreviation>. Has the same use-case as string, just adds flexibility to the type.
3. Function - expected to be the actual function from the Session This covers a use-case where the user can capture the function being used and programmatically trace it back to the rules being executed.

strict-map->Explanation clj

(strict-map->Explanation m26317 & [drop-extra-keys?__21456__auto__])

Factory function for class Explanation, taking a map of keywords to field values. All keys are required, and no extra keys are allowed. Even faster than map->

with-full-logging clj

Return a new session on which information will be gathered for optional inspection keys. This can significantly increase memory consumption since retracted facts cannot be garbage collected as normally.

without-full-logging clj

Return a new session without information gathering on this session for optional inspection keys. This new session will not retain references to any such information previously gathered.