Traces
Sentinel provides execution traces to better understand the execution of a policy.
When using the Sentinel CLI, traces are shown
on policy failure during apply
or test
, or when the -trace
flag is
explicitly specified. For Sentinel-enabled applications, traces are optional
and may require special configuration to enable.
The availability of the trace may vary from application to application. While some applications may only log traces on failure, others, such as Terraform Cloud, log the trace on every execution. For more details, consult your implementation's documentation.
Note: We're actively improving Sentinel tracing in each release to provide better data and improve readability. The exact format of a trace may not match the Sentinel version embedded in the application you're using, but the data should be similar. The canonical format for a trace should get more stable as we approach a 1.0 release.
Analyzing a Trace
To show traces, let's use the example policy below with the CLI:
Let's cause the policy to fail so the trace is more interesting. If you're on a terminal that supports it, the trace output will be colored so you can more clearly see passes, failures, and rules.
We can see all of our rules neatly and clearly displayed along with the result
of the policy. If you are getting the trace due to a failed policy and not
because you explicitly used -trace
, an informational message is displayed.
As we can see from our basic example, the main
rule has failed and its result
is highlighted in red. All peripheral rules that were also evaluated as part of
the policy are also displayed below the main rule. Source positions are also
displayed so that you can find the references to the rules in your code.
Via the trace, we can clearly see that while is_open_hours
returned a true
result, is_weekday
did not, and per the logic in our code, the policy is
rejected.
Non-Boolean Rules and the Trace
The trace is particularly important when working with rules that return non-boolean data, such as rules where you want to see violations instead of a simple opaque boolean value. Let's take our example from the rules section, and write a small static policy for it:
Sentinel Playground
Loading the playground...
Press "Run" to get policy output
Here is the output of our policy:
We can now see all of the weekdays with non-sunny weather.
Note that to prevent formatting issues and excessive output, the human-readable trace is limited in the volume of output it will display for collections.
JSON Output
The trace can also be displayed in JSON by adding -json
to sentinel apply
and sentinel test
, and will display the trace in its entirety, unlike the
standard CLI output.
Here is the result of running sentinel apply -json
against our weather policy:
Note that the trace is always included with this output, regardless of whether
or not the policy passes or fails; using -trace
is unnecessary.
Additionally, with sentinel apply
, you can display the value of a single rule
in JSON, instead of the entire trace. This is done with the -json-rule
flag.
Note: sentinel apply -json-rule
needs to be run either against a single
on-disk policy, or against a single policy within a policy set. It is ignored
in full policy set executions and functions exactly like -json
in these
scenarios.
Here is the result of executing sentinel apply -json-rule main weather.sentinel
:
Other Trace Details
There are some other details that are good to know when working with the trace:
- Only rules that get executed are added to the trace. Considering our first
example where the
main
rule is the expressionis_open_hours and is_weekday
, if our expression was using anor
operator instead ofand
, in addition to the policy passing,is_open_hours
would be present in the trace, butis_weekday
would not be, as the policy would have never evaluated that rule. - Descriptions for both rules and policies will show up in the trace as well if present. Here is the output to our first policy with the appropriate annotations: