This section outlines the various tools and techniques that can be used to debug OPA, both as a component in a distributed system and as a policy engine evaluating Rego.

Debugging Rego Policies

At its core, OPA is a policy engine evaluating policies written in Rego. There are a number of options available for users to debug Rego policies.

OPA REPL and Playground

Often it can take a few tries to get a Rego policy correct, the OPA REPL and Playground are great tools for reducing the feedback loop when debugging policies.

The REPL can be run locally and loaded with the policy and data files you are working on:

opa run [policy-files] [data-files]

The Rego Playground is a web-based Rego development environment that can be used to test policies with different inputs and data. If you are interested in asking for help in the OPA Slack, the playground is a great way to share your policy and data with others.

Performance Profiling

Sometimes the issue isn’t the correctness of the policy but rather the performance. The Policy Performance section of the documentation outlines various techniques for profiling and optimizing Rego policies.

Using the print Built-in Function

The print built-in function can be used to print values to stdout, this can be useful for checking values during policy evaluation as well as seeing how many times a particular line of code is executed.

See the print function documentation for more details on how to use the print built-in function in different contexts.

Ecosystem Projects

Below are ecosystem projects related to Debugging Rego. Integrations are ordered by the amount of linked content.

Regal

The Linter of Rego Language by Styra

Regal can be used to debug Rego policies by identifying common mistakes. See Bugs for some example issues it can identify automatically.

Regal also implements a language server and debug adapter for Rego to allow clients to debug Rego code as users type.

View Regal Details

VS Code Extension

OPA Integration for the VS Code editor by Styra

The extension provides support for debugging Rego policies using the native VS Code debugging interface. This is based on Regal’s Debug Adapter, see the VS Code documentation to get started.

View VS Code Extension Details

OPA Errors

OPA error message reference by Styra

OPA Errors is a guide aimed at helping users debug OPA errors by documenting common errors and fixes in detail.

View OPA Errors Details

OPA Playground

Online Rego Playground by Styra

The playground is a great place to debug Rego policies as you can quickly iterate on the policy and data at the same time before sharing links to collaborate on a fix with others.

View OPA Playground Details

rego-test-assertions

Helper functions for unit testing Rego by Anders Eknert

The rego-test-assertions library is designed to make debugging Rego tests easier.

View rego-test-assertions Details

View these projects in the OPA Ecosystem.

Debugging OPA Instances in Distributed Systems

Debugging problems in distributed systems poses a number of challenges. Since OPA is commonly deployed in a distributed fashion, as part of a larger platform, it is helpful to understand the various tools and techniques available for debugging OPA in these environments.

OPA Logs

OPA logs are a great place to start when debugging issues. The logs can be used to understand what OPA is doing at any given time. Common issues such as failing to load in policy or data bundles will be shown here.

You can also enable debug logging to get more detailed information about what OPA is doing with --log-level debug. This is documented in the CLI documentation for opa run.

Decision Logging

When OPA responds to a query, it is making a decision based on the policy and data that it has loaded. With the default logging configuration, these are not logged in detail to the OPA logs. However, it is possible to enable console decision logging by setting the following in OPA’s config file:

decision_logs:
  console: true

It might be preferable to send these logs to an HTTP endpoint or other system, to learn more about decision logging, take a look at the Decision Logging documentation.

Metrics, Health and Status APIs

Like other cloud-native tools, OPA exposes /metrics and /health endpoints that can be used to understand the state of an OPA instance at any given time.

• /metrics - exposes Prometheus metrics about the OPA instance’s memory use, bundle loading and HTTP requests. Read more in the Metrics documentation.
• /health - shows information about the instance’s readiness to serve requests, there are options available to also show information about the loading of bundles and other plugins. Read more about the endpoint in the Health API documentation.
• /status - is a JSON formatted endpoint that shows both health and metrics information. Read more in Status API documentation.

Manually Querying OPA

In distributed systems, it’s common that an OPA instance is being invoked by another service, sometimes it can be helpful to isolate the OPA instance and query it directly. This can be done using the REST API.

For example, to get a snapshot of the data that OPA has loaded, you can use the following command:

curl --silent https://$OPA_HOSTNAME/v1/data

Or to manually evaluate a policy rule with some input:

curl -X POST https://$OPA_HOSTNAME/v0/data/example_package/example_rule -d '{"foo": "bar"}'

Load a Production Bundle Locally

Sometimes there are too many moving parts in a distributed system to debug an issue effectively on a live system. In these cases, it can be helpful to load a bundle into a local OPA instance and debug the issue there.

You can quickly start an OPA instance with a remote bundle using the following command:

opa run -s https://example.com/bundles/bundle.tar.gz

If you need to configure the OPA instance with other options, you can use a config file to make more detailed configurations. Read more in the Configuration documentation documentation.