Decision Trace
When a policy-based decision is made during evaluation, a corresponding trace is generated. This trace output is designed to explain not just what decision was made, but why that decision was made. This includes citing versions and subsets of policy logic that triggered the decision, the context that acted as input to that logic, the categories that were valid for the stated purpose, and other details that collectively provide transparency and integrity around the decision process.
Tranquil Data offers connectors to take this trace and make it actionable in BI tools like Tableau. To help you build your own connectors, the full format of the trace is provided here.
Configuring Trace Levels#
Trace output for both log and Kafka strems can be configured as follows:
| Log Level | Resulting Trace Details |
|---|---|
none |
No trace is output |
failures |
Only output the trace for unsatisfied evaluation (which includes redaction results) |
all |
Output trace for all decisions |
Each entry in the trace represents a single evaluation.
Trace Structure#
The base structure of trace output is always the same, with the log level affecting which sub-elements are included.
TraceResult#
The top-level result of an evaluation trace includes details about where and when the evaluation ran and how decisions were interpreted by the engine. It includes nested details about specific evaluation details. A Result trace is formatted like this:
| Field Name | Type | Details |
|---|---|---|
| domain | string | The name of the domain where the evaluation occurred |
| checkpoint | integer | The logical time when this evaluation occurred |
| traceid | integer | The unique identifier for this trace (also included in associated change data capture) |
| satisfied | boolean | true if the policy was satisfied by context |
| requestTime | string | An RFC3339-formatted timestamp when the evaluation started |
| policySet | PolicySetTrace | The domain's policy set (or absent if the domain uses a policy) |
| policy | PolicyTrace | The domain's policy (or absent if the domain uses a policy set) |
Note that if the log level excludes policy details, then neither policy nor policySet will be included in the trace.
PolicySetTrace#
The trace for a specific Policy Set includes high-level knowledge about what happened in the scope of this set as well as nested evaluation details. A Policy Set trace is formatted like this:
| Field Name | Type | Details |
|---|---|---|
| identifier | string | The identifier for the evaluated policy set |
| decision | Permit, Deny, Indeterminate or NotApplicable |
The result of evaluation |
| targets | array of EvaluationTrace | A (possibly absent) array of target logic that was evaluated |
| policySets | array of PolicySetTrace | A (possibly absent) array of policy sets that were evaluated |
| policies | array of PolicyTrace | A (possibly absent) array of policies that were evaluated |
| references | array of ReferenceTrace | A (possibly absent) array of policies that were referenced |
| annotations | array of string | A (possibly absent) array of strings in the form "KEY=VALUE" that serve as annotation about the evaluation of this set |
| error | string | In the event of an error in evaluation, an explanation of the error |
Note that if the log level excludes evaluation details, then targets will not be included in the trace.
ReferenceTrace#
The trace for a Policy Reference explains what remote policy was referenced and whether that policy was resolved. A Reference trace is formatted like this:
| Field Name | Type | Details |
|---|---|---|
| identifier | string | The identifier for the referenced policy |
| found | boolean | true if the policy was successfully resolved |
| type | Policy or PolicySet |
The type of policy being referenced |
| error | string | In the event of an error resolving the policy, an explanation of the error |
PolicyTrace#
The trace for a specific Policy includes high-level knowledge about what happened in the scope of the policy as well as nested evaluation details. A Policy trace is formatted like this:
| Field Name | Type | Details |
|---|---|---|
| identifier | string | The identifier for the evaluated policy set |
| decision | Permit, Deny, Indeterminate or NotApplicable |
The result of evaluation |
| targets | array of EvaluationTrace | A (possibly absent) array of target logic that was evaluated |
| rules | array of RuleTrace | A (possibly absent) array of rules that were evaluated |
| annotations | array of string | A (possibly absent) array of strings in the form "KEY=VALUE" that serve as annotation about the evaluation of this policy |
| error | string | In the event of an error in evaluation, an explanation of the error |
Note that if the log level excludes evaluation details, then neither targets nor rules will not be included in the trace.
RuleTrace#
The trace for a given Rule includes details about evaluating both the condition and qualifier (obligations and advice) logic. A Rule trace is formatted like this:
| Field Name | Type | Details |
|---|---|---|
| identifier | string | The identifier for the evaluated rule |
| decision | Permit, Deny, Indeterminate or NotApplicable |
The result of evaluation |
| condition | array of EvaluationTrace | A (possibly absent) array of evaluations done to evaluate conditions |
| qualifiers | array of EvaluationTrace | A (possibly absent) array of evaluations done to discharge qualifiers |
| error | string | In the event of an error in evaluation, an explanation of the error |
EvaluationTrace#
The trace for an evaluation includes the details that went into this evaluation and its ultimate applicability, as well as any nested evaluations done to provide input. An Evaluation trace is formatted like this:
| Field Name | Type | Details |
|---|---|---|
| applies | boolean | true if the evaluation applied to the request |
| functions | array of FunctionTrace | |
| attributes | array of AttributeTrace | |
| error | string | In the event of an error in evaluation, an explanation of the error |
Note that in a given evaluation there may be functions or attributes, but not both.
FunctionTrace#
The trace for the evaluation of a single function includes knowledge about all nested inputs to that function, as well as the value that the function returned. A Function trace is formatted like this:
| Field Name | Type | Details |
|---|---|---|
| identifier | string | The identifier for the function that was evaluated |
| result | string | The value the function returned, in canonical string form |
| parameters | array of AttributeTrace | Any |
| functions | array of FunctionTrace | |
| error | string | In the event of an error in evaluation, an explanation of the error |
AttributeTrace#
The trace for attribute resolution includes details about what attribute was requested and what values were resolved. An Attribute trace looks like this:
| Field Name | Type | Details |
|---|---|---|
| identifier | string | The identifier for the attribute being resolved |
| category | string | The category of the the attribute being resolved |
| values | array of string | The (possibly absent) resolved values, in canonical string form |
| error | string | In the event of an error in resolution, an explanation of the error |