Skip to content

Commit

Permalink
docs: Update documentation to show Debug API uses
Browse files Browse the repository at this point in the history 
This three projects (VSCode OPA, nvim-dap-rego, and Regal) building on
this API, I've attempted to update the docs in the right places to
showcase these and their utility to rego authors.

Signed-off-by: Charlie Egan <[email protected]>
  • Loading branch information
@charlieegan3
charlieegan3 committed Sep 18, 2024
1 parent 9daad4b commit 54a235b
Show file tree
Hide file tree
Showing 7 changed files with 101 additions and 42 deletions.
31 changes: 21 additions & 10 deletions debug/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,23 @@
# OPA Debug API

This directory contains the OPA Debug API.
The Debug API facilitates programmatic debugging of Rego policies, on top of which 3rd parties can build tools for debugging.
This directory contains the OPA Debug API. The Debug API facilitates
programmatic debugging of Rego policies, on top of which 3rd parties can build
tools for debugging.

This API takes inspiration from the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/),
and follows the conventions established therein for managing threads, breakpoints, and variable scopes.
This API takes inspiration from the
[Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/),
and follows the conventions established therein for managing threads,
breakpoints, and variable scopes.

> **Note**: The Debug API is experimental and subject to change.
> [!TIP]
> The Debug API current actively supported in two clients
> [VS Code](https://github.com/open-policy-agent/vscode-opa) and
> [Neovim](https://github.com/rinx/nvim-dap-rego/tree/main). Both
> [Regal's Debug Adapter](https://docs.styra.com/regal/debug-adapter) as the
> backend, which is based on this API.
> [!WARNING]
> The Debug API is experimental and subject to change.
## Creating a Debug Session

Expand Down Expand Up @@ -178,11 +189,11 @@ allow if {

The current values of local and global variables are organized into scopes:

* `Local`: contains variables defined in the current rule, function, comprehension, or every expression.
* `Virtual Cache`: contains the state of the global Virtual Cache, where calculated return values for rules and functions are stored.
* `Input`: contains the input document.
* `Data`: contains the data document.
* `Result Set`: contains the result set of the current query. This scope is only available on the final expression of the query evaluation.
- `Local`: contains variables defined in the current rule, function, comprehension, or every expression.
- `Virtual Cache`: contains the state of the global Virtual Cache, where calculated return values for rules and functions are stored.
- `Input`: contains the input document.
- `Data`: contains the data document.
- `Result Set`: contains the result set of the current query. This scope is only available on the final expression of the query evaluation.

```go
scopes, err := session.Scopes(thread.ID)
Expand Down
41 changes: 28 additions & 13 deletions docs/content/debugging.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,28 @@ kind: documentation
weight: 75
---

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.
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 the Rego language.

# 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.
Debugging Rego is crucial to ensuring OPA functions properly, as its policy
engine evaluates policies written in Rego. Effective Rego debugging helps
identify and resolve issues that impact OPA’s performance and behavior. A strong
grasp of Rego debugging is key to ensuring the correct functioning of OPA as a
whole.

## Live Debugging

Using the [Debug Adapter](https://docs.styra.com/regal/debug-adapter)
based on [OPA's Debug API](https://github.com/open-policy-agent/opa/blob/main/debug/README.md),
supported clients are now able to live debug Rego line by line. Breakpoints,
variable inspection and print statements are all supported.

Read more about the supported editors of this debugging method in the
[Regal Editor Support Page](https://docs.styra.com/regal/editor-support).

{{< figure src="debugging-dap.gif" width="65" caption="Debugging Rego in <a href='/integrations/vscode-opa/'>VS Code</a>" >}}

## OPA REPL and Playground

Expand All @@ -28,12 +43,6 @@ used to test policies with different inputs and data. If you are interested in a
[OPA Slack](http://slack.openpolicyagent.org), 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](../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
Expand All @@ -42,6 +51,12 @@ during policy evaluation as well as seeing how many times a particular line of c
See the [print function documentation](../policy-reference/#debugging) for more details on how to use
the `print` built-in function in different contexts.

## Performance Profiling

Sometimes the issue isn't the correctness of the policy but rather the performance. The
[Policy Performance](../policy-performance) section of the documentation outlines various techniques for
profiling and optimizing Rego policies.

## Ecosystem Projects

{{< ecosystem_feature_embed key="debugging-rego" topic="Debugging Rego" >}}
Expand Down Expand Up @@ -79,12 +94,12 @@ take a look at the [Decision Logging documentation](../management-decision-logs)
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.
- `/metrics` - exposes Prometheus metrics about the OPA instance's memory use, bundle loading and HTTP requests.
Read more in the [Metrics documentation](../monitoring).
* `/health` - shows information about the instance's readiness to serve requests, there are options available to also
- `/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](../rest-api/#health-api).
* `/status` - is a JSON formatted endpoint that shows both health and metrics information. Read more in
- `/status` - is a JSON formatted endpoint that shows both health and metrics information. Read more in
[Status API documentation](../rest-api/#status-api).

## Manually Querying OPA
Expand Down
36 changes: 23 additions & 13 deletions docs/content/editor-and-ide-support.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,30 @@ evaluation, policy coverage, and more.

## Integrations

> Note: See each integration for what features are supported! Not all support the same features.
| Editor | Link | Note |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Visual Studio Code | [marketplace.visualstudio.com/items?itemName=tsandall.opa](https://marketplace.visualstudio.com/items?itemName=tsandall.opa) | Supports Language Server and Debug Adapter |
| Neovim | Syntax highlighting [tree-sitter-rego](https://github.com/FallenAngel97/tree-sitter-rego), Language server [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#regal), Debugger [nvim-dap](https://github.com/mfussenegger/nvim-dap) + [nvim-dap-rego](https://github.com/rinx/nvim-dap-rego) | Supports Language Server and Debug Adapter |
| Zed | [github.com/StyraInc/zed-rego](https://github.com/StyraInc/zed-rego) | Supports Language Server |
| IntelliJ IDEA | [github.com/open-policy-agent/opa-idea-plugin](https://github.com/open-policy-agent/opa-idea-plugin) | |
| Vim | [github.com/tsandall/vim-rego](https://github.com/tsandall/vim-rego) | |
| Emacs | [github.com/psibi/rego-mode](https://github.com/psibi/rego-mode) | |
| Nano | [github.com/scopatz/nanorc](https://github.com/scopatz/nanorc) | |
| Sublime Text | [github.com/open-policy-agent/opa/tree/main/misc/syntax/sublime](https://github.com/open-policy-agent/opa/tree/main/misc/syntax/sublime) | |
| TextMate | [github.com/open-policy-agent/opa/tree/main/misc/syntax/textmate](https://github.com/open-policy-agent/opa/tree/main/misc/syntax/textmate) | |
| Atom | [github.com/open-policy-agent/opa/tree/main/misc/syntax/atom](https://github.com/open-policy-agent/opa/tree/main/misc/syntax/atom) | The Atom editor is [no longer maintained](https://github.blog/news-insights/product-news/sunsetting-atom/). |

| Editor | Link |
| --- | --- |
| Atom | [https://github.com/open-policy-agent/opa/tree/main/misc/syntax/atom](https://github.com/open-policy-agent/opa/tree/main/misc/syntax/atom) |
| Emacs | [https://github.com/psibi/rego-mode](https://github.com/psibi/rego-mode) |
| IntelliJ IDEA | [https://github.com/open-policy-agent/opa-idea-plugin](https://github.com/open-policy-agent/opa-idea-plugin) |
| Nano | [https://github.com/scopatz/nanorc](https://github.com/scopatz/nanorc) |
| Sublime Text | [https://github.com/open-policy-agent/opa/tree/main/misc/syntax/sublime](https://github.com/open-policy-agent/opa/tree/main/misc/syntax/sublime) |
| TextMate | [https://github.com/open-policy-agent/opa/tree/main/misc/syntax/textmate](https://github.com/open-policy-agent/opa/tree/main/misc/syntax/textmate) |
| Vim | [https://github.com/tsandall/vim-rego](https://github.com/tsandall/vim-rego) |
| Visual Studio Code | [https://marketplace.visualstudio.com/items?itemName=tsandall.opa](https://marketplace.visualstudio.com/items?itemName=tsandall.opa) |
| Zed | [https://github.com/StyraInc/zed-rego](https://github.com/StyraInc/zed-rego) |
{{< info >}}
**Your editor missing? Built a Rego integration for your editor?** Drop us a
message on [Slack](http://slack.openpolicyagent.org)
We also have our [Ecosystem page](/ecosystem/). This is a great place to
showcase your project. See
[these instructions](https://github.com/open-policy-agent/opa/tree/main/docs#opa-ecosystem)
to get it listed.
{{</ info >}}

## Rego Playground

The Rego Playground provides a great editor to get started with OPA and share policies. Try it out at [https://play.openpolicyagent.org/](https://play.openpolicyagent.org/)
The Rego Playground provides a great editor to get started with OPA and share
policies. Try it out at
[play.openpolicyagent.org](https://play.openpolicyagent.org/).
Binary file added docs/content/images/debugging-dap.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/website/assets/sass/custom.sass
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@

figcaption
font-style: normal !important
font-size: 1.5rem
font-size: 1.2rem
font-weight: 500

.tag
Expand Down
18 changes: 15 additions & 3 deletions docs/website/content/integrations/regal.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,22 @@ docs_features:
Regal can be used to debug Rego policies by identifying common mistakes.
See [Bugs](https://docs.styra.com/regal/category/bugs) for some example
issues it can identify automatically.
Regal also implements a
[language server](https://docs.styra.com/regal/language-server) and
[debug adapter](https://docs.styra.com/regal/debug-adapter) for Rego to
allow clients to debug Rego code as users type.
---

Regal is a linter for Rego, with the goal of making your Rego magnificent!

Regal can:
* Identify common mistakes, bugs and inefficiencies in Rego policies, and suggest better approaches
* Provide advice on best practices, coding style, and tooling
* Allow users, teams and organizations to enforce custom rules on their policy code

- Identify common mistakes, bugs and inefficiencies in Rego policies, and suggest better approaches
- Provide advice on best practices, coding style, and tooling
- Allow users, teams and organizations to enforce custom rules on their policy code

Regal also implements a
[language server](https://docs.styra.com/regal/language-server) and
[debug adapter](https://docs.styra.com/regal/debug-adapter) for Rego to
allow clients to debug Rego code as users type.
15 changes: 13 additions & 2 deletions docs/website/content/integrations/vscode-opa.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,18 @@ docs_features:
such as syntax highlighting, running of OPA tests as well as
completions, linting and more from the
[Regal Language Server](/integrations/regal/).
debugging-rego:
note: |
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](https://docs.styra.com/regal/editor-support#visual-studio-code)
to get started.
---

The [vscode-opa extension](https://marketplace.visualstudio.com/items?itemName=tsandall.opa) is a Visual Studio Code extension that provides support for the Rego language and OPA functionality. The extension includes syntax highlighting,
and support for the [Regal Language Server](/integrations/regal/).
The [vscode-opa extension](https://marketplace.visualstudio.com/items?itemName=tsandall.opa)
is a Visual Studio Code extension that provides support for the Rego language
and OPA functionality. The extension includes syntax highlighting, and first
class support for the Regal
[Language Server](https://docs.styra.com/regal/language-server) and
[Debug Adapter](https://docs.styra.com/regal/debug-adapter).

0 comments on commit 54a235b

Please sign in to comment.