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.

What is Debug mode?

Permit's Debug Mode adds additional debug information to your decision logs, allowing for an in-depth analysis of the decisions made by your PDP.

The advantages of Debug Mode

On top of standard log information provided by our Audit Logs, Debug Mode allows us to understand -

• Why a decision was made
• Which policy was taken into consideration for the evaluation process
• What are the policies currently configured in your environment

This information gives you a more granular understanding of any decision made by the PDP.

danger

Turning on Debug Mode will impact policy evaluation latency. Thus, it is recommended to disable Debug Mode when running in production.

Configuring 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 as part of the PDP deployment.
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:

docker run -it \
  -p 7766:7000 \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  --env PDP_DEBUG=True \
  permitio/pdp-v2:latest

note

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:

   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

     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

     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.
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 change the default Debug Mode behavior on the PDPs in this environment.

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.

Performance Impact

Having debug mode activated has a performance penalty and is recommended to run with it disabled on production environments.
For more information about performance optimizations for production environments, please read the full documentation here