Tracing

The JSON result of an evaluation tells you what a rule decided, but not how it got there. When an output is incorrect, a signal fires unexpectedly, or a map, filter, or reduce produces an unexpected value, a trace lets you follow the evaluation step by step. It shows each operation in order, the values passed to it, every lambda invocation, and the final slot state.

Pass --trace to eval to print the trace report instead of the JSON result.

Running a trace

nodora compile -f RiskAssessment.ruleset -o RiskAssessment.json
nodora eval -f RiskAssessment.json -r RiskAssessment -i input.json --trace

--trace (alias --debug) prints a human-readable report and suppresses the JSON output:

--- trace RiskAssessment ---

input
  ...

steps
  0  [1] = input.risk_score >= 80
         = 90 >= 80  => true
  ...

Reading the report

The report has a few sections:

• input shows the input object as the rule sees it.
• steps lists each operation in execution order. The first line is the operation as written ([1] = input.risk_score >= 80); the second line substitutes the actual values and shows the result after => (90 >= 80 => true).
• A call such as map, filter, or reduce expands into a tree with one branch per invocation. Each branch shows the argument bound to a parameter with <= and the value the invocation produced with =>.
• outputs pairs each output with the slot its value came from.
• signals lists the signals emitted during the run.
• slotdump shows the final value of every slot.

Using traces to diagnose errors

A trace is useful in a few common situations:

• When an output is wrong, follow the steps to the first operation whose result looks off and read the substituted operands.
• When a signal fired (or did not), the emit line is marked emitted or not emitted and shows its guard as a concrete value.
• For higher-order calls, the tree shows what each element produced, or which elements a filter kept and which it dropped.
• When evaluation hits a runtime error, the failing step is marked with error:, and the report still shows every step that ran before it.

Large lambdas

For a map or filter over a big array, only the first few invocations are shown.

Raise the limit with --trace-lambda-frames:

nodora eval -f rules.json -r Batch -i input.json --trace --trace-lambda-frames 20