From cab6a4ae6e4e8f25a5b2296a7d97cbb2732a7273 Mon Sep 17 00:00:00 2001 From: ivanauth Date: Tue, 20 Jan 2026 12:40:31 -0500 Subject: [PATCH] docs: add tracing examples and fix formatting --- app/spicedb/concepts/commands/page.mdx | 48 ++----- .../validation-testing-debugging/page.mdx | 119 +++++++++++++++++- wordlist.txt | 3 +- 3 files changed, 127 insertions(+), 43 deletions(-) diff --git a/app/spicedb/concepts/commands/page.mdx b/app/spicedb/concepts/commands/page.mdx index f3cd5078..7761aa48 100644 --- a/app/spicedb/concepts/commands/page.mdx +++ b/app/spicedb/concepts/commands/page.mdx @@ -27,14 +27,13 @@ A database that stores and computes permissions ### Children commands -- [spicedb datastore](#reference-spicedb-datastore) - datastore operations -- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol -- [spicedb man](#reference-spicedb-man) - Generate man page -- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw) - serve a Postgres Foreign Data Wrapper for SpiceDB (EXPERIMENTAL) -- [spicedb serve](#reference-spicedb-serve) - serve the permissions database -- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore -- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB - +- [spicedb datastore](#reference-spicedb-datastore) - datastore operations +- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol +- [spicedb man](#reference-spicedb-man) - Generate man page +- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw) - serve a Postgres Foreign Data Wrapper for SpiceDB (EXPERIMENTAL) +- [spicedb serve](#reference-spicedb-serve) - serve the permissions database +- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore +- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB ## Reference: `spicedb datastore` @@ -50,11 +49,10 @@ Operations against the configured datastore ### Children commands -- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection -- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available -- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations -- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair - +- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection +- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available +- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations +- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair ## Reference: `spicedb datastore gc` @@ -145,8 +143,6 @@ spicedb datastore gc [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb datastore head` compute the head (latest) database migration revision available @@ -178,8 +174,6 @@ spicedb datastore head [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb datastore migrate` Executes datastore schema migrations for the datastore. @@ -219,8 +213,6 @@ spicedb datastore migrate [revision] [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb datastore repair` Executes a repair operation for the datastore @@ -310,8 +302,6 @@ spicedb datastore repair [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb lsp` serve language server protocol @@ -335,12 +325,10 @@ spicedb lsp [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb man` Generate a man page for SpiceDB. - The output can be redirected to a file and installed to the system: +The output can be redirected to a file and installed to the system: ``` spicedb man > spicedb.1 @@ -348,7 +336,6 @@ Generate a man page for SpiceDB. sudo mandb # Update man page database ``` - ``` spicedb man ``` @@ -361,8 +348,6 @@ spicedb man --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb postgres-fdw` EXPERIMENTAL: Serves a Postgres-compatible interface for querying SpiceDB data using foreign data wrappers. This feature is experimental and subject to change. @@ -391,8 +376,6 @@ spicedb postgres-fdw [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb serve` start a SpiceDB server @@ -577,8 +560,6 @@ spicedb serve [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb serve-testing` An in-memory spicedb server which serves completely isolated datastores per client-supplied auth token used. @@ -640,8 +621,6 @@ spicedb serve-testing [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb version` displays the version of SpiceDB @@ -663,6 +642,3 @@ spicedb version [flags] --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") --skip-release-check if true, skips checking for new SpiceDB releases ``` - - - diff --git a/app/spicedb/modeling/validation-testing-debugging/page.mdx b/app/spicedb/modeling/validation-testing-debugging/page.mdx index 04973c1b..6ac4b59c 100644 --- a/app/spicedb/modeling/validation-testing-debugging/page.mdx +++ b/app/spicedb/modeling/validation-testing-debugging/page.mdx @@ -25,7 +25,9 @@ You can run the integration test server by executing `spicedb serve-testing` or 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. -To support this, SpiceDB's v1 CheckPermission API supports a debug header that will cause SpiceDB to trace the full set of relations and permission traversed while computing the check. +**This method is deprecated.** As of v1.30.0+, use the [Check Tracing](#check-tracing) method with `withTracing: true` instead, which returns trace data directly in the response body. + +In versions prior to v1.30.0, this method uses gRPC metadata headers to request debug trace information, with the trace data returned in the response trailer. **Warning:** @@ -38,9 +40,24 @@ Instead, we recommend using [zed's explain flag] for this purpose. -Configuring this header is done by setting the header `io.spicedb.requestdebuginfo` to the string `true`. +To request debug information, set the header `io.spicedb.requestdebuginfo` to `1`. + + + **Note:** In SpiceDB v1.30.0+, this header still works but the trace data is + returned in the response body (`debugTrace` field) rather than the trailer. + The trailer `io.spicedb.respmeta.debuginfo` will contain a message indicating + to check the response body instead. + + +#### Example + +Using the `zed` CLI with the `--explain` flag (recommended): -The response will include a trailer, `io.spicedb.respmeta.debuginfo`, with a JSON-encoded tree. +```sh +zed permission check --explain document:firstdoc view user:fred +``` + +This will print a visual tree of the permission check trace. ## Playground @@ -150,15 +167,105 @@ project:docs#admin: ## Check Tracing +**This is the modern, recommended method for collecting trace information** (available in SpiceDB v1.30.0+). Unlike the legacy [CheckPermission Tracing Header](#checkpermission-tracing-header) approach (which returned trace data in a response trailer in versions prior to v1.30.0), this method returns the trace as a structured field directly in the response message body. + 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. +To request tracing information, set `withTracing: true` in the request message. The trace data will be returned in the response message. + +**Key differences from the header-based approach:** + +- More structured and easier to parse programmatically +- Preferred for modern integrations - **Warning:** In versions older than v1.31.0, request tracing information via a - header and the information will be found in the response footer as JSON. + **Warning:** In versions older than v1.30.0, you must request tracing + information via a header, and the trace data will be returned in the response + trailer as JSON. +#### Example Request/Response + +**Request** (using grpcurl): + +```sh +grpcurl \ + -H "Authorization: Bearer your-token-here" \ + -d '{ + "resource": {"objectType": "document", "objectId": "firstdoc"}, + "permission": "view", + "subject": {"object": {"objectType": "user", "objectId": "fred"}}, + "withTracing": true + }' \ + your-spicedb-instance:443 \ + authzed.api.v1.PermissionsService/CheckPermission +``` + +**Response**: + +```json +{ + "permissionship": "PERMISSIONSHIP_HAS_PERMISSION", + "checkedAt": { + "token": "GhUKEzE3MDYxMTIwMDAwMDAwMDAwMDA=" + }, + "debugTrace": { + "check": { + "resource": { + "objectType": "document", + "objectId": "firstdoc" + }, + "permission": "view", + "permissionType": "PERMISSION_TYPE_PERMISSION", + "subject": { + "object": { + "objectType": "user", + "objectId": "fred" + } + }, + "result": "PERMISSIONSHIP_HAS_PERMISSION", + "duration": "0.000125s", + "subProblems": { + "traces": [ + { + "resource": { + "objectType": "document", + "objectId": "firstdoc" + }, + "permission": "reader", + "permissionType": "PERMISSION_TYPE_RELATION", + "subject": { + "object": { + "objectType": "user", + "objectId": "fred" + } + }, + "result": "PERMISSIONSHIP_HAS_PERMISSION", + "duration": "0.000045s" + } + ] + } + }, + "schemaUsed": "definition document {\n relation reader: user\n permission view = reader\n}\n\ndefinition user {}" + } +} +``` + +The `debugTrace` field contains a `DebugInformation` object with: + +- `check`: A `CheckDebugTrace` object containing the trace tree +- `schemaUsed`: The schema that was used for the check + +Each `CheckDebugTrace` includes: + +- `resource`: The resource being checked +- `permission`: The permission or relation name +- `permissionType`: Whether it's a `PERMISSION_TYPE_PERMISSION` or `PERMISSION_TYPE_RELATION` +- `subject`: The subject of the check +- `result`: The permissionship result +- `duration`: Time spent on this check (as a Duration string, e.g., "0.000125s") +- `subProblems`: Contains `traces` array with nested `CheckDebugTrace` objects, or `wasCachedResult: true` if cached + ## Zed ### Zed Validate diff --git a/wordlist.txt b/wordlist.txt index 85c64af2..bf293c74 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -1,4 +1,4 @@ -personal_ws-1.1 en 654 +personal_ws-1.1 en 655 ABAC ACKing ACL @@ -440,6 +440,7 @@ goroutines governance gpg grpc +grpcurl grpcutil hashlib heredoc