Debugging Requests

While it is recommended that SpiceDB schema be validated and tested before production deployment, there are many scenarios in which being able to see the actual paths taken against production data is incredibly important.

To support this use case the CheckPermission API supports a special debug header which can be used to retrieve the full set of relations and permission traversed in order to compute the result.

Displaying explanations via zed

The simplest way to use the tracing system is to use the zed (opens in a new tab) CLI tool with the --explain flag:

zed permission check --explain document:firstdoc view user:fred

Example output:

true
✓ document:firstdoc view (66.333µs)
├── ⨉ document:firstdoc writer (12.375µs)
└── ✓ document:firstdoc reader (20.667µs)
    └── user:fred 

Cached results

If the result for a CheckPermission has already been cached by SpiceDB, then that will be indicated:

true
✓ document:firstdoc view (cached)
└── user:fred 

Cycle detection

If the schema and relationships within SpiceDB forms a cycle, it will be indicated in the output:

! document:foo view
├── ✕ document:foo viewer
└── ! document:bar view
    ├── ✕ document:bar viewer
    └── ! document:baz view
        ├── ✕ document:baz viewer
        └── ! document:foo view (cycle)

Using the tracing API directly

If you wish to call CheckPermission and retrieve the debug traces directly, there are a few steps involved:

1. Set the header (opens in a new tab) io.spicedb.requestdebuginfo to value true on the request
2. Retrieve the trailer (opens in a new tab) io.spicedb.respmeta.debuginfo and parse the JSON found within as a DebugInformation (opens in a new tab) message.