Ruleset debugging tools

Use the Rule Designer debug tools to make sure that your rule application projects run as expected.

Debug mode

You can run a ruleset in debug mode to test rules, inspect execution of rules and engine state, and set breakpoints on classes, objects, rules, decision tables and trees, and rule flows.

In Rule Designer, you can debug both rule code and Java™ code in a project.

The Debug views are useful when you start testing and debugging the execution of your rules. The debugger monitors business rule execution by checking the ruleset, connecting to a rule engine, sending the ruleset to the engine, resetting the engine, and executing all the rules.

Debug actions
With the debugger, you can control the process of business rule execution:
  • Step into, step over, and step return in any rule or code statement:
    • Step over: to go to the next rule statement.
    • Step into: to go to the next rule statement or stop in the next Java statement.
    • Step return: to go to the next rule statement that is not defined in the current rule artifact.
  • Drop to frame or use step filters. Use Window > Preferences > Java > Debug > Step Filtering to set debug filters. (On Mac, click Eclipse  > Preferences > Java > Debug > Step Filtering.)
  • Resume, suspend, and terminate.
  • Set breakpoints on rules, classes, and objects.
Debug mode performance
You can improve the performance of ruleset parsing when you are debugging a rule project in Eclipse by disabling this option: Window > Preferences > Java > Debug > Suspend execution on compilation error (On Mac, click Eclipse  > Preferences > Java > Debug > Suspend execution on compilation error)
Note: The improvement factor depends on your Java virtual machine. Even when this preference is turned off, the debug mode remains slower than the regular run mode.

Debug view

The Debug view displays the stack frame for the suspended threads for each target you are debugging. You can get a stack trace of the execution history.

From the Debug view, you can manage the debugging of a rule project or any Java program in the workbench. It displays the stack frame for the suspended threads for each target you are debugging. Each thread is shown as a node in the tree.

The Debug view does not provide a history of all the events occurring in the rule engine. However, a stack trace is a useful debugging tool, particularly when an exception has been thrown in the code or when a method is called from a variety of places within your code and you want to learn from where it is called when a particular problem occurs.

You can get stack trace information of the execution history. The stack lists the classes, and the methods within those classes, that are called at the point where the exception occurs through programmatic access. For example, you can use the StackTraceElement class and the getStackTrace method of the Throwable class.

You can also generate a partial Java stack trace by using the static Thread.dumpStack method or the printStackTrace method of the Throwable class.

If the JVM experiences an internal error, it calls its own signal handler to print out the threads and monitors information.

Working memory

The Working Memory view display the objects in working memory for the RetePlus execution mode. Use it with the Agenda view to easily check whether the rules behave as expected.

The view can display the value and type of the various fields of the object. From that view, you can dynamically inspect the objects as they affect the rules. This is important to check whether a rule behaves correctly. For example, you can easily check the behavior of the rules currently in the agenda that use a specific value.

Agenda

The Agenda view displays any rule instances scheduled for execution in RetePlus mode. Use it with the Working Memory view to quickly debug your applications.

The values in the Working Memory view are updated when the engine is updated. The view can display the priority of a rule in the agenda and the objects used by it. In conjunction with the Working Memory view, it provides you with a powerful way to debug an application quickly.

Variables

The Variables view displays the names of the variables currently bound to a business rule and the parameters currently visible in the engine.

For example, if the ShoppingCart object is bound to a variable called ?shoppingCart in one of the rules, the Variables view shows this relationship. The values in the Variables view are updated after the evaluation of each expression.

Breakpoints

The Breakpoints view displays the breakpoints that stop the execution of rules at any point to examine the state of variables, the agenda, and working memory.

You can set breakpoints on the following elements:

  • Rule expressions

  • XOM classes and class members

  • Objects in the working memory

You can set breakpoints in the following rule artifacts:

  • BAL rules (in the action part)

  • Technical rules

  • Decision tables and decision trees (in an action cell)

  • Functions

  • Ruleflows

  • Rule tasks (in the Ruleflow Editor)

  • Working memory of the rule engine (when executing with the RetePlus execution mode)

  • Business object model (BOM)

  • BOM-to-XOM mapping code

Console

The Console view displays messages that have been sent to the output stream associated with the engine.

The Console shows the following text:

  • Standard output

  • Standard error

  • Standard input