Merge pull request #215 from authzed/check-tracing

Add basic check tracing doc

Author: samkim

pages/spicedb/modeling/validation-testing-debugging.mdx

@@ -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
 
@@ -35,11 +35,13 @@ To support this, SpiceDB's v1 CheckPermission API supports a debug header that w
   Instead, we recommend using [zed's explain flag] for this purpose.
 
   [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
@@ -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
 
@@ -85,6 +88,19 @@ 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.
+
+Request tracing information by setting `with_tracing: true` in the request message and the information will be found in the response message.
+
+<Callout type="warning">
+  **Warning:**
+  Versions older than v1.31.0
+
+  Request tracing information via a header and the information will be found in the response footer as JSON.
+</Callout>
+
 ## Zed
 
 ### Zed Validate
@@ -109,13 +125,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)
-    └── [38;5;99muser:fred [0m
+   └── [38;5;99muser:fred [0m
 ```
 
 This command will also highlight which parts of the traversal were cached and if a cycle is detected.
@@ -142,8 +158,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.