Skip to main content

​
Policy Preview Overview (Growth Plan)

Policy Preview is a beta CL feature that benchmarks query performance for a candidate policy — a new or modified policy you’re testing — and compares it to your current production policy. Use this tool to test policy changes during development or enforce performance checks in CI pipelines.

​
Requirements

  • Growth plan subscription
  • Oso Cloud CLI, version >= 0.35.1
  • A candidate policy to compare against your deployed policy
  • A list of queries to benchmark

​
Quick Start

  1. Create a query manifest (e.g. queries.yaml)
A YAML file that defines queries to preview. See Query Manifest Reference for details. 
# Example
queries:
  - name: "Admins can read repos"
    query_type: authorize
    actor_type: User
    actor_id: alice
    action: read
    resource_type: Repository
    resource_id: backend-repo

  - name: "List of repos Alice can read"
    query_type: list
    actor_type: User
    actor_id: alice
    action: read
    resource_type: Repository
  1. Create a candidate policy with your proposed changes You can use a single .polar file (e.g. candidate.polar) or multiple .polar files (e.g. policies/*.polar).
  2. Run the preview
oso-cloud experimental policy-preview --queries queries.yaml policies/*.polar
This command runs all queries against both your production and candidate policies, then displays a side-by-side performance comparison.
  1. Configure Policy Preview options
You can configure thresholds that mark queries as failed when exceeded, adjust the timeout setting for individual queries, or toggle on cache state views:
FlagDescription
-f,
--fail-on-regression-percent		Fail if any query is slower by this percentage
(e.g., 20 for 20%)
-i,
--ignore-changes-under-ms		Ignore regressions smaller than this threshold in milliseconds
(e.g., 10)
--max-duration-msFail if any query exceeds this absolute duration in milliseconds
(e.g., 750)
--max-regression-msFail if any query slows down by more than this many milliseconds
(e.g., 200)
--show-cold-cacheShow both cold and warm cache performance
(default: warm cache only)
--timeout-msTimeout in milliseconds for each individual query
(default: 1000ms, max: 5000ms)
Queries that exceed thresholds appear as failed in the terminal output and cause the command to exit with code 1. Note: By default, individual queries that take longer than 1 second to evaluate will time out. You can adjust this time up to 5 seconds with --timeout-ms. A query fails if:
  • It times out with the candidate policy but not the current one, or
  • It times out with both policies.

​
Query Manifest Reference

The manifest file defines the queries to execute during policy preview. It supports the following query types: The query structure is similar to the HTTP API, with two additional required fields: name and query_type.

​
Manifest Structure

queries:
  - name: "Query name"
    query_type: <type>
    # Additional fields depend on query type

​
Query Types

​
Authorize Query

- name: <String> (must be unique)
  query_type: authorize
  actor_type: <String>
  actor_id: <String>
  action: <String>
  resource_type: <String>
  resource_id: <String>

​
List Query

- name: <String> (unique)
  query_type: list
  actor_type: <String>
  actor_id: <String>
  action: <String>
  resource_type: <String>

​
Actions Query

- name: <String> (unique)
  query_type: actions
  actor_type: <String>
  actor_id: <String>
  resource_type: <String>
  resource_id: <String>

​
Evaluate Query

- name: <String>
  query_type: evaluate_query
  predicate: [<String>]
  calls:
    - [<String>]
  constraints:
    <String>:
      type: <String>
      ids: [<String>]
    <String>:
      type: <String>
Required fields:
  • predicate: Array where first element is predicate name, the rest are variable names
  • constraints: Map of variable names to constraint definitions
    • type: Entity type for the variable
    • ids (optional): List of IDs to test
  • All variables in predicate or calls must be defined in constraints
Optional fields:
  • calls: Array of predicate calls formatted like predicate

​
Context Facts

You can add context facts to any of the above queries. If you add a context fact to a query, each of these fields below are required: 
context_facts:
  - predicate: <String>
    args:
      - type: <String>
        id: <String>
      - type: <String>
        id: <String>
      - type: <String>
        id: <String>

​
Output Format

Policy Preview outputs results in a formatted table comparing baseline and candidate performance, showing regressions, improvements, and failures: Policy Preview Output

​
Best Practices

​
Create Representative Query Sets

Include queries that represent:
  • Common authorization paths
  • Edge cases
  • Performance-critical queries
  • Recently changed policy rules

​
Troubleshooting

​
”Feature not enabled” error

Policy Preview must be enabled. Contact us on Slack to gain access.

​
YAML parsing errors

Check your manifest structure. Common issues include:
  • Missing required fields
  • Incorrect indentation
  • Unknown fields