Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add basic check tracing doc #215

Merged
merged 4 commits into from
Apr 9, 2024
Merged

Add basic check tracing doc #215

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
828357e
Add basic check tracing doc
josephschorr Mar 14, 2024
fde9224
PR feedback
samkim Apr 5, 2024
282324c
Use warning callout
samkim Apr 9, 2024
47ec4cb
Add spacing
samkim Apr 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 25 additions & 10 deletions pages/spicedb/modeling/validation-testing-debugging.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { Callout } from 'nextra/components'
import YouTube from 'react-youtube'
import { Callout } from 'nextra/components';
import YouTube from 'react-youtube';

# Validation, Testing, Debugging SpiceDB Schemas

Expand Down Expand Up @@ -31,15 +31,17 @@ To support this, SpiceDB's v1 CheckPermission API supports a debug header that w
**Warning:**
Collecting these traces has a notable performance overhead.

We do not recommend configuring your applications to enable this when debugging.
Instead, we recommend using [zed's explain flag] for this purpose.
We do not recommend configuring your applications to enable this when debugging.
Instead, we recommend using [zed's explain flag] for this purpose.

[zed's explain flag]: #explain-flag

[zed's explain flag]: #explain-flag
</Callout>

Configuring this header is done by setting the header `io.spicedb.requestdebuginfo` to the string `true`.

The response will include a trailer, `io.spicedb.respmeta.debuginfo`, with a JSON-encoded tree.

## Playground

### Assertions
Expand All @@ -62,7 +64,8 @@ This enables an even tighter feedback-loop when developing a schema.

Below is an example of configuring a Check Watch:

<br /><YouTube videoId="UmvGPU8iQ-0" />
<br />
<YouTube videoId="UmvGPU8iQ-0" />

### Expected Relations

Expand All @@ -85,6 +88,18 @@ project:docs#admin:
- "[user:rauchg] is <platform:vercel#admin>"
```

## Check Tracing

SpiceDB supports tracing of check requests to view the path(s) taken to compute the result, as well as timing information.

### Versions older than v1.31.0

Request tracing information via a header and the information is found in the response footer as JSON.

### v1.31.0 or later

Request tracing information by setting `with_tracing: true` in the request message and the information is found in the response message.

## Zed
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it might be a better structure to the page if this just documents the v1.31 behavior with a warning about using the header for older versions rather than having two additional layers of nesting headings.


### Zed Validate
Expand All @@ -109,13 +124,13 @@ If you're interested in learning more about this functionality in SpiceDB, you c

Here's an example using `--explain`:

```ansi
```ansi
$ zed permission check --explain document:firstdoc view user:fred
true
✓ document:firstdoc view (66.333µs)
├── ⨉ document:firstdoc writer (12.375µs)
└── ✓ document:firstdoc reader (20.667µs)
└── user:fred 
└── user:fred 
```

This command will also highlight which parts of the traversal were cached and if a cycle is detected.
Expand All @@ -142,8 +157,8 @@ steps:
### [authzed/action-spicedb-validate](https://github.com/marketplace/actions/validate-spicedb-schema)

<Callout type="info">
**Info:**
This tool is highly recommended because it can prevent deployments of unverified changes.
**Info:** This tool is highly recommended because it can prevent deployments
of unverified changes.
</Callout>

The Playground offers a variety of tools that are useful for validating a design, but running the playground isn't designed for operating within a typical CI/CD environment.
Expand Down
Loading