docs: Add a new debugging page (open-policy-agent#6513)

This page is intended to be a starting point for users debugging various
OPA issues. It outlines various OPA features that can help narrowing
down issues in one place.

Signed-off-by: Charlie Egan <charlie@styra.com>

docs/content/debugging.md

@@ -0,0 +1,119 @@
+---
+title: Debugging OPA
+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.
+
+# 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:
+
+```shell
+opa run [policy-files] [data-files]
+```
+
+The [Rego Playground](http://play.openpolicyagent.org) 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](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
+during policy evaluation as well as seeing how many times a particular line of code is executed.
+
+See the [print function documentation](../policy-reference/#debugging) for more details on how to use
+the `print` built-in function in different contexts.
+
+## Ecosystem Projects
+
+{{< ecosystem_feature_embed key="debugging-rego" topic="Debugging Rego" >}}
+
+# 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](../cli/#options-10) 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:
+
+```yaml
+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](../management-decision-logs).
+
+## Metrics, Heath 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](../monitoring).
+* `/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 API documentation](../rest-api/#status-api).
+
+## 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](../rest-api).
+
+For example, to get a snapshot of the data that OPA has loaded, you can use the following command:
+
+```shell
+curl --silent https://$OPA_HOSTNAME/v1/data
+```
+
+Or to manually evaluate a policy rule with some input:
+
+```shell
+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:
+
+```shell
+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](../configuration) documentation.

docs/website/content/ecosystem/debugging-rego.md

@@ -0,0 +1,8 @@
+---
+title: Debugging Rego
+description: Work out what's going on with your Rego policies
+category: rego
+---
+
+Debugging Rego policies can be tricky. These projects and tools can help you
+work out what's going on.

docs/website/content/integrations/opa-errors.md

@@ -0,0 +1,27 @@
+---
+title: OPA Errors
+subtitle: OPA error message reference
+labels:
+  category: learning
+inventors:
+- styra
+code:
+- https://docs.styra.com/opa/errors
+tutorials:
+- https://docs.styra.com/opa/errors
+docs_features:
+  debugging-rego:
+    note: |
+      [OPA Errors](https://docs.styra.com/opa/errors) is a guide aimed at
+      helping users debug OPA errors by documenting common errors and fixes in
+      detail.
+---
+
+[OPA Errors](https://docs.styra.com/opa/errors) is a guide is designed to help
+you understand the most common errors you'll encounter when working with OPA.
+Each page provides examples of an OPA error, why it's an error,
+and how to fix it.
+
+If you'd like to request that a new error is listed, please drop us a message in
+the
+[Styra Slack](https://communityinviter.com/apps/styracommunity/signup).

docs/website/content/integrations/opa-playground.md

@@ -24,5 +24,10 @@ docs_features:
       your first policies. You can also share links if you're asking for
       help in the community Slack. Get started with a simple
       [RBAC example](https://play.openpolicyagent.org/p/Bb9FqBvauC).
+  debugging-rego:
+    note: |
+      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.
 ---
 Interactive online Rego playground for writing and sharing policies

docs/website/content/integrations/regal.md

@@ -34,6 +34,11 @@ docs_features:
       code is correct and free of common errors. See
       [the README](https://github.com/StyraInc/regal#try-it-out)
       to get started.
+  debugging-rego:
+    note: |
+      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 is a linter for Rego, with the goal of making your Rego magnificent!
 

docs/website/content/integrations/rego-test-assertions.md

@@ -0,0 +1,28 @@
+---
+title: rego-test-assertions
+subtitle: Helper functions for unit testing Rego
+labels:
+  category: library
+inventors:
+- anderseknert
+code:
+- https://github.com/anderseknert/rego-test-assertions
+tutorials:
+- https://github.com/anderseknert/rego-test-assertions/blob/main/README.md
+docs_features:
+  policy-testing:
+    note: |
+      The [rego-test-assertions](https://github.com/anderseknert/rego-test-assertions)
+      library contains various assertion functions, which will print the
+      expected result vs. the outcome to the console on failure.
+  debugging-rego:
+    note: |
+      The [rego-test-assertions](https://github.com/anderseknert/rego-test-assertions)
+      library is designed to make debugging Rego tests easier.
+---
+
+A Rego library providing helper functions for unit testing. The library
+primarily contains various assertion functions, which will print the expected
+result vs. the outcome to the console on failure. This allows you to quickly
+grasp what went wrong in your unit tests, resulting in a faster test iteration
+process!

docs/website/content/organizations/anderseknert.md

@@ -0,0 +1,4 @@
+---
+link: https://www.eknert.com
+title: Anders Eknert
+---