chore: add documentation of LR debugging#547
Open
tstirrat15 wants to merge 2 commits intomainfrom
Open
Conversation
Contributor
|
Preview deployment status for this pull request.
|
tstirrat15
force-pushed
the
tstirrat/lr-cyclic-relationship-debug
branch
from
1e25c75 to
854b335
Compare
miparnisari
reviewed
Apr 29, 2026
|
|
||
| Note that the `parent` relation on the `folder` definition is recursive, and that we've written a `parent` relationship from `folder:a` to `folder:b` and vice versa, creating a cycle. | ||
|
|
||
| If you run `zed import` on this file, and then run `zed permission lookup-resources lookup-resources resource view user:someuser`, you'll get a `max depth exceeded` error. |
Contributor
There was a problem hiding this comment.
Suggested change
| If you run `zed import` on this file, and then run `zed permission lookup-resources lookup-resources resource view user:someuser`, you'll get a `max depth exceeded` error. | |
| If you run `zed import` on this file, and then run `zed permission lookup-resources resource view user:someuser`, you'll get a `max depth exceeded` error. |
miparnisari
reviewed
Apr 29, 2026
Comment on lines
+26
to
28
| SpiceDB supports tracing of check requests to view the path(s) taken to compute the result, as well as timing information. | ||
|
|
||
| While it is recommended that SpiceDB schema be validated and tested before production deployment, there are many scenarios where being able to see the actual paths taken against production data is incredibly important. |
Contributor
There was a problem hiding this comment.
Suggested change
| SpiceDB supports tracing of check requests to view the path(s) taken to compute the result, as well as timing information. | |
| While it is recommended that SpiceDB schema be validated and tested before production deployment, there are many scenarios where being able to see the actual paths taken against production data is incredibly important. | |
| Sometimes you may need to see exactly which relationship paths led to a result in a CheckPermission query. To this end, the [CheckPermission](https://buf.build/authzed/api/docs/main%3Aauthzed.api.v1#authzed.api.v1.CheckPermissionRequest) API supports adding a boolean `withTracing` request parameter. | |
miparnisari
reviewed
Apr 29, 2026
| </Callout> | ||
|
|
||
| Configuring this header is done by setting the header `io.spicedb.requestdebuginfo` to the string `true`. | ||
| Configuring this header is done by setting the `with_tracing` field on the [CheckDebugRequest](https://buf.build/authzed/api/docs/main%3Aauthzed.api.v1#authzed.api.v1.CheckPermissionRequest) to `true`. |
Contributor
There was a problem hiding this comment.
Suggested change
| Configuring this header is done by setting the `with_tracing` field on the [CheckDebugRequest](https://buf.build/authzed/api/docs/main%3Aauthzed.api.v1#authzed.api.v1.CheckPermissionRequest) to `true`. |
miparnisari
reviewed
Apr 29, 2026
| information will be found in the response footer as JSON. | ||
| </Callout> | ||
|
|
||
| ## Zed |
Contributor
There was a problem hiding this comment.
similar to the "explain flag" section:
can you add a "debug flag" section for LR?
also, in "explain flag", can you get rid of the "tracing header" sentence? i feel like it adds no value, the section is self-explanatory
miparnisari
reviewed
Apr 29, 2026
|
|
||
| - The lines should be read as resources with the relation connecting them to the previous pair. For example, in the line marked by `(cycle)` can be read eas "there's a `view` relation between `folder:a` and `folder:b`." | ||
| - The relation can a schema relation, a schema permission, or a schema subject relation. Notice that in the line marked by `cycle`, the relation is `view`, corresponding to the `view` permission on the `folder` definition in the schema. This means that you might need to do some translation to connect the relation in a line to a concrete relationship. | ||
| - The `(cycle)` marks the endpoints where a resource that is a member of a cycle was seen for the second time. It does _not_ mean that the marked relation is the offending relation, just that everything between the marks is a member of the cycle. You'll need to think about which relationships are written where to understand what needs to change in your business logic to avoid the cycle. |
Contributor
There was a problem hiding this comment.
the other two bullets feel useless to me; i'd get rid of them. the third is the bullet that is important.
miparnisari
reviewed
Apr 29, 2026
Comment on lines
+238
to
+251
| You'll get output that looks like this: | ||
|
|
||
| ``` | ||
| The following resource/relation pairs were found in a cycle in LookupResources: | ||
|
|
||
| - folder:a#view | ||
|
|
||
| To further debug this, issue a check from the resource to itself across the relation. | ||
| For example, with the identified pair `resource:foo#view`, you would make the following call: | ||
|
|
||
| zed permission check resource:foo view resource:foo --explain | ||
|
|
||
| For more information, see the LookupResources section under https://spicedb.dev/d/debug-max-depth | ||
| ``` |
Contributor
There was a problem hiding this comment.
i feel iffy about pasting the literal error here, which can change in the future. why not just say "use --debug which will give you more information"?
and the following paragraphs are more about zed permission check --explain than about LR 😅
tstirrat15
force-pushed
the
tstirrat/lr-cyclic-relationship-debug
branch
from
f50fbf8 to
e3875fe
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The documentation component of authzed/spicedb#3070. This adds instructions on how to read and interpret the output.
Changes
Testing
Review.