From 828357efa8d02af8b34cb9b79c5230098ea4952d Mon Sep 17 00:00:00 2001 From: Joseph Schorr Date: Thu, 14 Mar 2024 11:48:47 -0400 Subject: [PATCH 1/4] Add basic check tracing doc --- .../modeling/validation-testing-debugging.mdx | 30 ++++++++++++------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/pages/spicedb/modeling/validation-testing-debugging.mdx b/pages/spicedb/modeling/validation-testing-debugging.mdx index e48a582..ba85ab2 100644 --- a/pages/spicedb/modeling/validation-testing-debugging.mdx +++ b/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 @@ -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 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: -
+
+ ### Expected Relations @@ -85,6 +88,13 @@ project:docs#admin: - "[user:rauchg] is " ``` +## Check Tracing + +SpiceDB supports tracing of check requests to view the path(s) taken to compute the result, as well as timing information. + +This information is requested via a header (versions older than v1.31.0) or setting `with_tracing: true` (v1.31.0 or later), and +the trace information can be found in the footer as JSON (versions older than v1.31.0) or in the response message itself (v1.31.0 or later). + ## Zed ### Zed Validate @@ -109,13 +119,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. @@ -142,8 +152,8 @@ steps: ### [authzed/action-spicedb-validate](https://github.com/marketplace/actions/validate-spicedb-schema) - **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. 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. From fde92241a75de6bd7a97a6686de5799a7b96343f Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Fri, 5 Apr 2024 13:30:06 -0700 Subject: [PATCH 2/4] PR feedback --- .../modeling/validation-testing-debugging.mdx | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/pages/spicedb/modeling/validation-testing-debugging.mdx b/pages/spicedb/modeling/validation-testing-debugging.mdx index ba85ab2..8a80bd1 100644 --- a/pages/spicedb/modeling/validation-testing-debugging.mdx +++ b/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 @@ -92,8 +92,13 @@ project:docs#admin: SpiceDB supports tracing of check requests to view the path(s) taken to compute the result, as well as timing information. -This information is requested via a header (versions older than v1.31.0) or setting `with_tracing: true` (v1.31.0 or later), and -the trace information can be found in the footer as JSON (versions older than v1.31.0) or in the response message itself (v1.31.0 or later). +### 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 From 282324c31e5035a0a7ea64c5685ed54a6ee60d29 Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Tue, 9 Apr 2024 11:16:14 -0700 Subject: [PATCH 3/4] Use warning callout --- .../spicedb/modeling/validation-testing-debugging.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/pages/spicedb/modeling/validation-testing-debugging.mdx b/pages/spicedb/modeling/validation-testing-debugging.mdx index 8a80bd1..ccf2ab0 100644 --- a/pages/spicedb/modeling/validation-testing-debugging.mdx +++ b/pages/spicedb/modeling/validation-testing-debugging.mdx @@ -92,13 +92,15 @@ project:docs#admin: 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 by setting `with_tracing: true` in the request message and the information will be found in the response message. -Request tracing information via a header and the information is found in the response footer as JSON. + + **Warning:** + Versions older than v1.31.0 -### v1.31.0 or later +Request tracing information via a header and the information will be found in the response footer as JSON. -Request tracing information by setting `with_tracing: true` in the request message and the information is found in the response message. + ## Zed From 47ec4cb6aa7fe28f007194f16a946c7e15efb647 Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Tue, 9 Apr 2024 13:38:33 -0700 Subject: [PATCH 4/4] Add spacing --- pages/spicedb/modeling/validation-testing-debugging.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/pages/spicedb/modeling/validation-testing-debugging.mdx b/pages/spicedb/modeling/validation-testing-debugging.mdx index ccf2ab0..b581bb5 100644 --- a/pages/spicedb/modeling/validation-testing-debugging.mdx +++ b/pages/spicedb/modeling/validation-testing-debugging.mdx @@ -31,10 +31,10 @@ 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 @@ -98,8 +98,7 @@ Request tracing information by setting `with_tracing: true` in the request messa **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. - + Request tracing information via a header and the information will be found in the response footer as JSON. ## Zed