fix the documentation about the debug mode (#394)

* fix the documentation about the debug mode

* improve the pdp debug documentation

* reorder notes

* add better explanation about the debug mode env var

* change the negative title of disadvantages

* merge the default behavior and superseding hierarchy

docs/concepts/pdp/configuration.mdx

@@ -31,9 +31,16 @@ The URL of the Permit.io control plane.
 
 #### PDP_DEBUG
 
-Default: `False`
+Default: `None`
+
+PDP debug mode configuration.
+There available configurations are:
+- `PDP_DEBUG=None` - The default behavior, will use the configuration set by Permit.io Cloud.
+- `PDP_DEBUG=True` - Will enable Debug Mode for this specific PDP.
+- `PDP_DEBUG=False` - Will disable Debug Mode for this specific PDP.
 
-Enabled PDP debug mode. See more details about [PDP Debug Mode](/how-to/use-audit-logs/debug-mode/).
+For more detailed configuration about the PDP Debug Mode,
+please check the full documentation [here](/how-to/use-audit-logs/debug-mode/).
 
 #### PDP_SHARD_ID
 

docs/how-to/use-audit-logs/debug-mode.mdx

@@ -3,6 +3,7 @@ sidebar_position: 3
 title: Debug Mode
 ---
 
+
 Knowing why some decisions were made by your PDP can be a crutial part of buidling and understanding your policies, especially when you encounter unexpected results.
 That's what **Debug Mode** is here for.
 
@@ -24,14 +25,17 @@ This information gives you a more granular understanding of any decision made by
 Turning on Debug Mode will impact policy evaluation latency. Thus, it is recommended to disable Debug Mode when running in production.
 :::
 
-## Activating Debug Mode
+## Configuring Debug Mode
 
-There are two possible ways to activate Debug Mode:
+There are few possible ways to configure Debug Mode:
 
 ### Through the PDP environment variables:
 
-When running your PDP, set the environment variable `PDP_DEBUG=True` as part of the PDP deployment.
-This will activate Debug Mode for this specific PDP.
+When running your PDP, set the environment variable `PDP_DEBUG` as part of the PDP deployment. <br />
+There available configurations are:
+- `PDP_DEBUG=None` - The default behavior, will use the configuration set by Permit.io Cloud.
+- `PDP_DEBUG=True` - Will enable Debug Mode for this specific PDP.
+- `PDP_DEBUG=False` - Will disable Debug Mode for this specific PDP.
 
 Here's an example of such a PDP deployment:
 
@@ -47,11 +51,60 @@ docker run -it \
 This configuration will only enable Debug Mode in the PDP itself and not across your environment.
 :::
 
+### Through the Permit API
+
+Updating the Debug Mode configuration can also be done via the Permit API.
+To do se you can use the following guide:
+
+1. Extract the relevant PDP Configuration from the Permit API:
+    ```bash
+    curl "https://api.permit.io/v2/pdps/{proj_id}/{env_id}/configs" \
+    -H "Authorization: Bearer {api-key}"
+    ```
+2. Update the setting for the relevant PDP Configuration using the id retrieved from the previous call:
+    - To enable use the following command
+        ```bash
+        curl "https://api.permit.io/v2/pdps/{proj_id}/{env_id}/configs/{pdp_id}/debug-audit-logs/enable" \
+        -X PUT \
+        -H "Authorization: Bearer {api-key}"
+        -H 'Content-Type: application/json'
+        ```
+    - To disable use the following command
+        ```bash
+        curl "https://api.permit.io/v2/pdps/{proj_id}/{env_id}/configs/{pdp_id}/debug-audit-logs/disable" \
+        -X PUT \
+        -H "Authorization: Bearer {api-key}"
+        -H 'Content-Type: application/json'
+        ```
+
+:::note
+Updating the configuration via the API will affect all PDPs using the updated PDP Configuration in the environment.<br />
+The PDP Config the PDP is using is determined based on the API Key the PDP runs with.
+
+:::
+
+
 ### Through the UI (Coming Soon)
 
 Another option to enable Debug Mode is through Permit's UI. To do that:
 
 1. Go to your Permit dashboard and make sure you have the relevant project and environment selected.
 2. Next, go to the **Audit Log** screen.
 3. In the top right corner, click on **Settings**.
-4. Click the toggle to enable Debug Mode.
+4. Click the toggle to change the default Debug Mode behavior on the PDPs in this environment.
+
+
+:::note Default Behavior & Superseding Hierarchy
+The configuration hierarchy for Debug Mode is as follows:
+- If no configuration was set, the PDP will show debug information.
+- If the configuration was set on Permit.io Cloud, the PDP will use that configuration.
+- If the configuration was set on the PDP itself, it will override the Permit.io Cloud configuration.
+- If the API/SDK Call to the PDP was done with `use_debugger` in the body, it will override any other configuration set.
+:::
+
+:::warning Performance Impact
+Having debug mode activated has a performance penalty and is recommended to run
+with it disabled on production environments.<br />
+For more information about performance optimizations for production environments, please read the full documentation [here](/how-to/deploy/deploy-to-production#general-performance-tips)
+:::
+