Visual tracing

A visual trace is an interactive HTML diagram of how the policy engine evaluated a test request: which policy sets, policies, and rules it evaluated, what each of them returned, and which attribute values it used. Use it when a test returns an unexpected decision, to find the rule that made the decision and why. For problems with the tests themselves, ADS, or attribute connectors, use the logs, see Logging.

Where to find the trace

For each test on the embedded policy engine, APD writes the trace to build/alfa/tests/trace/<test method>_visualize.html, and prints its location in the test output:

Visualization report at file:///…/build/alfa/tests/trace/shouldGiveCeciliaAccessToResource1_visualize.html

Open the file in a browser. Tests against a running ADS have no visual trace.

Turn visual tracing off

Visual tracing is on by default. Writing the traces takes time, so you can turn it off, for example on a build server. Set withVisualTrace to false in the alfa block of your build.gradle file:

build.gradle

alfa {
    mainpolicy "acme.Main"
    withVisualTrace false
}

To keep the trace for the tests of one class, turn it on in the class with withEvaluationTrace(). This applies even when withVisualTrace is false:

@RegisterExtension
public AlfaExtension alfa = new AlfaExtension().withEvaluationTrace();

Interface

The trace shows the evaluation as a tree, with the main policy at the root:

• Nodes: each node is a policy set, policy, rule, or attribute value, colored by its result, see Decision states. An evaluated node also shows its evaluation time, and its share of the total.
• Hover over a node to see its details: the name, type, decision, combining algorithm, effect, errors, and evaluation time. For an attribute, the details also show where its value came from: the request, or an attribute connector, and whether the value was cached.
• Click a node to show only that part of the tree. Use the Back button of your browser to return.

Side panel

Control	Function	Shortcut
Show not evaluated nodes	Shows the policy elements that were not evaluated.	E
Developer mode	Expands targets, conditions, advice, and obligations, to show the functions and attribute values inside them. By default, the tree stops at these elements.	D
Horizontal layout	Changes the orientation of the tree from vertical to horizontal.	H
View	Changes what the tree shows: Policy (the default), Dictionary, Attribute connectors, or Request.	V

Interpret the trace

Decision states

Each node is colored by its result. See the legend in the side panel for the colors.

State	Meaning
Permit (or true)	The policy or rule evaluated to Permit (for a target or condition, true).
Deny (or false)	The policy or rule evaluated to Deny (for a target or condition, false).
NotApplicable	The policy or rule did not apply: its target did not match the request, or the condition of the rule was false.
Indeterminate	An error occurred during the evaluation. Hover over the node to see the error.
NotEvaluated	The element was not evaluated, for example because an earlier rule already decided the result. Hidden by default. Select Show not evaluated nodes to show it.

Find the rule that made the decision

1. Start at the root, the main policy, and note its decision.
2. Follow the nodes with the same decision down the tree. With combining algorithms such as first-applicable or deny-overrides, this leads to the rule that decided the result.
3. Hover over the nodes on the way to see their combining algorithm and decision. Turn on Developer mode to see the target and condition of a rule, with the attribute values they used.

Common patterns to investigate

• Unexpected NotApplicable on a rule: the target of the rule did not match the request, or its condition was false. Turn on Developer mode to see the target and condition with the attribute values they used, and compare them with what the rule expects.
• Wrong combining algorithm outcome: if several rules apply, check whether the combining algorithm (first-applicable, deny-overrides, and so on) gives the result you expect.
• Short-circuit evaluation: when a combining algorithm stops early, for example after the first applicable rule, the later rules are not evaluated and appear as NotEvaluated. This is normal, not an error.