Skip to main content

Overview

The decision log records the policy decisions that OPA makes, regardless which kind of real-world system OPA is integrated with. Each decision log entry records the inputs that OPA was given, the decision that OPA made, performance metrics for decision-making, decision metadata, and a pointer to the policy or data used to make that decision. Each decision log entry is stored as JSON. You can review why a decision was made the way it was or how a decision would be made with policy changes.

View the Decision Log​

To view the decision log for all Systems in Styra DAS, in the left navigation panel, under WORKSPACE, click the tenant name and then click the Decisions tab. Styra DAS displays all the decisions made across all systems. To view only the decisions for a single DAS System, click on a System in the left navigation panel and then click on the Decisions tab. Similarly, you can view the decisions for a DAS Stack.

Types of Decisions​

Every decision log entry is labeled as one of the following types:

  • Denied: Decision was to reject the attempted action.

  • Allowed: Decision was to accept the attempted action.

  • Advice: Decision cannot be categorized as either Allowed or Denied. In Kubernetes systems, Advice decisions represent a Mutation.

  • Error: An error occurred during policy evaluation.

  • Unknown: Decision cannot be categorized.

The Unknown label appears primarily for Custom Systems, custom policy types, or when a System's decision mapping is invalid or does not match the decision log output. For details on configuring decision logs, see decision log configuration.

note

In Kubernetes Systems, Mutation occurs before Validation. The resource (as the input) first is evaluated against Mutating policies, and, if applicable, a patch is applied by a Mutating rule. If a Mutating policy is triggered, the patched resource acts as an input to the Validating policies. The decision log for Validating policies (Allowed or Denied) displays the mutated or patched object in the logs as the input.

Find a Decision​

The following features will help you to find decisions of interest:

  • Filter: Enter a search term. For example, nginx to restrict decision log entries to those which include this term. Refer to Decision Search Language for additional details.

  • Live: Toggle updating the decision log in real-time as decisions are received and processed by Styra DAS.

  • Policy-type: For Systems or Stacks with multiple policy types (for example, Ingress and Egress), you can filter the decisions to those policy types.

  • Outcome: Filter decisions based on the decision outcome (Allowed, Denied, Advice, Error, or Unknown).

Analyze the Decision​

In the decision log, you can analyze a decision by doing the following actions.

  • Explore the contents of a decision by clicking the arrow on the left-hand side to reveal the full JSON entry. The following section details each field in the decision log, but the most important fields are:

    • path: Name of the policy that OPA evaluated.

    • input: The JSON object that OPA made a decision about.

    • result: The decision itself.

  • Replay the decision by clicking the replay button to the right of the decision label. Styra DAS will load the decision's input with the current policy version and evaluate the results, allowing you to see the decision result of your current policy. This also makes it easy to change the input to see how the decision would change.

  • Click on the Context button (three vertical dots ⋮) to:

    • Copy the decision: This will copy the JSON decision to your clipboard.

    • Copy the decision input: This will copy the JSON decision input to your clipboard.

    • Copy a link to the decision: This copies a link to your clipboard to share that decision.

    • Download the decision: This downloads the JSON decision to your device.

Decision Log Entry Fields​

The following shows the list of individual fields for each decision log entry in the order of importance:

  • path: The name of the policy that OPA evaluated (policies in OPA are arranged hierarchically).

  • input: The full input OPA used to make a decision (for example, Kubernetes expects an AdmissionReview request).

  • result: The result of policy evaluation (for example, Kubernetes expects an AdmissionReview response).

  • allowed: A boolean indicating whether the response was allowed or denied.

  • reason: A statement explaining why the decision was made.

  • error: The error object returned to the user if policy evaluation failed.

  • bundles: An identifier for the version of the policy (and all of its dependencies) for each bundle used to make the decision.

  • metrics: The metrics OPA recorded when making the decision. For example, the following shows the list of metrics:

    • timer_rego_module_parse_ns: Time (in nanoseconds) to read the policy into memory.

    • timer_rego_module_compile_ns: Time (in nanoseconds) to prepare the policy for evaluation.

    • timer_rego_query_parse_ns: Time (in nanoseconds) to read the query into memory.

    • timer_rego_query_compile_ns: Time (in nanoseconds) to prepare the query for evaluation.

    • timer_rego_query_eval_ns: Time to evaluate the query.

    • timer_server_handler_ns: Total time from when OPA received the query to the time it responded.

  • labels: The labels that OPA was configured with.

  • requested_by: The IP address and port of the service that requested a policy evaluation.

  • decision_id: A unique identifier generated by OPA.

  • agent_id: A unique identifier of the OPA instance responsible for the decision.

  • timestamp: Timestamp of the decision (OPA-side clock).

  • received: Timestamp when the decision log batch was received by Styra (server-side clock).

  • system_id: A unique identifier of the system.

  • columns: A list of user-defined column values reflecting values extracted from the decision result, input or other fields.

Decision Replay Mode​

The Decision Replay Mode explains which policies contributed to the selected decision. You can replay the decision by clicking the Replay button.

The Replay mode has the following behavior:

  • The default selected policy is set as the recommended policy.

  • Only policies highlighted in bold directly contributed to this replayed decision.

  • Additionally, this shows systems, stacks, and libraries that contributed to this replayed decision.

  • Normal file operations (such as deleting systems) are restricted.

The Decision Replay Mode label in the left navigation pane indicates replay mode is active. To exit the replay mode, click the close (X) button. To share the replayed decision link with other users, click the Get Link button.

While in the replay mode, you can also work on decisions in normal mode as follows:

  • Open and debug the same policy in normal mode using a different tab to preview or validate after making changes.

  • Understand why a policy does not appear in replay mode, which they expected to contribute to a decision and want to debug.

  • Compare the replay mode policy with another policy in normal mode.

In the above cases, you can exit the replay mode by changing the URL in a new browser tab. You can also return the UI to normal mode (non replay mode) by removing the query parameter mode=decisionReplay in the URL. To enable the replay mode, add the query parameter mode=decisionReplay in the URL. For example, /v1/...?mode=decisionReplay.

Styra DAS also loads the decision's input into the current policy and evaluates the results so that you can see what decision your current policy would make. This also makes it easy to change the input using the Preview button to see how the output would change.

Decision Replay Environment​

During decision replay, DAS automatically sets an OPA runtime environment variable (STYRA_DAS_REPLAY set to true) to denote that the decision context is a replay instead of a live decision. Policies can use this runtime environment variable to change their behavior during replay, such as using a different field if the original input field is masked or redacted during the original decision.

This is particularly useful for use cases where policies use a JWT or other token with potentially sensitive data is used for a decision. In these cases, users may use a decision mask to remove this sensitive data from the decision and add a non-sensitive decoded token value to a separate field. For example, the JWT verification in a Library used by multiple Systems, Stacks, and other Libraries could be updated to:

get_claims := x {
	opa.runtime().env.STYRA_DAS_REPLAY
	x := input.decoded_token
}
else := x {
	io.jwt.verify_rs256(input.token, "...")
	x := io.jwt.decode(input.token)
}

Retention Policy​

The decision log retention defaults are 336 hours (14 days) archiving of received OPA decision batches and 72 hours (3 days) for searchable decision logs.