Skip to main content

Turn on Debug Mode for decision logs

Turn on Debug Mode to add the reason behind each permission decision to your decision logs. This page is for developers who need to understand why a policy decision point (PDP) allowed or denied a request.

What Debug Mode adds to decision logs​

With Debug Mode on, the PDP adds a debug object to each decision. The debug object shows:

  • The request the PDP evaluated: the user and its attributes, whether the user is synced, the tenant, the action, and the resource.
  • For each policy model that took part in the decision, a code and a human-readable reason. For example, debug.rbac.reason names the role that granted access.
  • For a denied request, a support_link to the page that explains the code. See Denial codes in decision logs.
Debug Mode adds latency

Debug Mode increases policy evaluation latency. Turn off Debug Mode for PDPs that serve production traffic. For other production settings, see Performance settings.

Choose where to set Debug Mode​

Where you set itScopeUse it when
PDP_DEBUG environment variableOne PDP containerYou debug a single PDP, for example a local container.
Permit APIEvery PDP that uses the same PDP configurationYou change the setting for an environment's PDPs without redeploying them, including the Cloud PDP.
use_debugger in a PDP request bodyOne requestYou debug a single check.

When more than one setting applies, the most specific one wins:

  1. use_debugger in the request body overrides every other setting.
  2. PDP_DEBUG on the PDP container overrides the Permit API setting.
  3. The Permit API setting applies when neither of the settings above is set.
  4. When nothing is set, Debug Mode is on.

Set Debug Mode on one PDP container​

Set the PDP_DEBUG environment variable when you start the PDP container:

ValueBehavior
Not setThe PDP uses the setting from the Permit API. This is the default.
TrueDebug Mode is on for this PDP.
FalseDebug Mode is off for this PDP.

In this docker run command, replace <YOUR_API_KEY> with your environment API key:

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

PDP_DEBUG changes only this PDP. Other PDPs in the environment keep their setting. For every PDP variable, see PDP configuration.

Set Debug Mode for a PDP configuration with the Permit API​

A PDP configuration belongs to an environment. Every PDP that runs with an API key of that PDP configuration uses its Debug Mode setting, including the Cloud PDP.

Before you start, get your project ID (proj_id), environment ID (env_id), and an API key for the environment. See Get project and environment IDs and Get your API key.

  1. List the environment's PDP configurations, and copy the id of the PDP configuration to change:

    curl "https://api.permit.io/v2/pdps/{proj_id}/{env_id}/configs" \
    -H "Authorization: Bearer {api-key}"

  2. Use that id as {pdp_id}, and send one of these requests.

    • To turn Debug Mode on: 
      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 turn Debug Mode off: 
      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'

The change applies to every PDP that uses this PDP configuration. A PDP container that sets PDP_DEBUG keeps its own setting.

For the request and response schemas, see Enable debug audit logs in the API reference.

Confirm that Debug Mode is on​

  1. Run a permit.check() call against the PDP.
  2. Open the Audit Log screen in the Permit dashboard and select the new decision.

The decision log has a debug object with a reason. When Debug Mode is off, the decision log has no debug object.

Next steps​

Contents

Edit this page

Need help?