Skip to content

Commit cab6a4a

Browse files
ivanauthivanauth
committed
docs: add tracing examples and fix formatting
1 parent 940db39 commit cab6a4a

3 files changed

Lines changed: 127 additions & 43 deletions

File tree

‎app/spicedb/concepts/commands/page.mdx‎

Lines changed: 12 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,13 @@ A database that stores and computes permissions
2727

2828
### Children commands
2929

30-
- [spicedb datastore](#reference-spicedb-datastore) - datastore operations
31-
- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol
32-
- [spicedb man](#reference-spicedb-man) - Generate man page
33-
- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw) - serve a Postgres Foreign Data Wrapper for SpiceDB (EXPERIMENTAL)
34-
- [spicedb serve](#reference-spicedb-serve) - serve the permissions database
35-
- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore
36-
- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB
37-
30+
- [spicedb datastore](#reference-spicedb-datastore) - datastore operations
31+
- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol
32+
- [spicedb man](#reference-spicedb-man) - Generate man page
33+
- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw) - serve a Postgres Foreign Data Wrapper for SpiceDB (EXPERIMENTAL)
34+
- [spicedb serve](#reference-spicedb-serve) - serve the permissions database
35+
- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore
36+
- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB
3837

3938
## Reference: `spicedb datastore`
4039

@@ -50,11 +49,10 @@ Operations against the configured datastore
5049

5150
### Children commands
5251

53-
- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection
54-
- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available
55-
- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations
56-
- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair
57-
52+
- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection
53+
- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available
54+
- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations
55+
- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair
5856

5957
## Reference: `spicedb datastore gc`
6058

@@ -145,8 +143,6 @@ spicedb datastore gc [flags]
145143
--skip-release-check if true, skips checking for new SpiceDB releases
146144
```
147145

148-
149-
150146
## Reference: `spicedb datastore head`
151147

152148
compute the head (latest) database migration revision available
@@ -178,8 +174,6 @@ spicedb datastore head [flags]
178174
--skip-release-check if true, skips checking for new SpiceDB releases
179175
```
180176

181-
182-
183177
## Reference: `spicedb datastore migrate`
184178

185179
Executes datastore schema migrations for the datastore.
@@ -219,8 +213,6 @@ spicedb datastore migrate [revision] [flags]
219213
--skip-release-check if true, skips checking for new SpiceDB releases
220214
```
221215

222-
223-
224216
## Reference: `spicedb datastore repair`
225217

226218
Executes a repair operation for the datastore
@@ -310,8 +302,6 @@ spicedb datastore repair [flags]
310302
--skip-release-check if true, skips checking for new SpiceDB releases
311303
```
312304

313-
314-
315305
## Reference: `spicedb lsp`
316306

317307
serve language server protocol
@@ -335,20 +325,17 @@ spicedb lsp [flags]
335325
--skip-release-check if true, skips checking for new SpiceDB releases
336326
```
337327

338-
339-
340328
## Reference: `spicedb man`
341329

342330
Generate a man page for SpiceDB.
343-
The output can be redirected to a file and installed to the system:
331+
The output can be redirected to a file and installed to the system:
344332

345333
```
346334
spicedb man > spicedb.1
347335
sudo mv spicedb.1 /usr/share/man/man1/
348336
sudo mandb # Update man page database
349337
```
350338

351-
352339
```
353340
spicedb man
354341
```
@@ -361,8 +348,6 @@ spicedb man
361348
--skip-release-check if true, skips checking for new SpiceDB releases
362349
```
363350

364-
365-
366351
## Reference: `spicedb postgres-fdw`
367352

368353
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]
391376
--skip-release-check if true, skips checking for new SpiceDB releases
392377
```
393378

394-
395-
396379
## Reference: `spicedb serve`
397380

398381
start a SpiceDB server
@@ -577,8 +560,6 @@ spicedb serve [flags]
577560
--skip-release-check if true, skips checking for new SpiceDB releases
578561
```
579562

580-
581-
582563
## Reference: `spicedb serve-testing`
583564

584565
An in-memory spicedb server which serves completely isolated datastores per client-supplied auth token used.
@@ -640,8 +621,6 @@ spicedb serve-testing [flags]
640621
--skip-release-check if true, skips checking for new SpiceDB releases
641622
```
642623

643-
644-
645624
## Reference: `spicedb version`
646625

647626
displays the version of SpiceDB
@@ -663,6 +642,3 @@ spicedb version [flags]
663642
--log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info")
664643
--skip-release-check if true, skips checking for new SpiceDB releases
665644
```
666-
667-
668-

‎app/spicedb/modeling/validation-testing-debugging/page.mdx‎

Lines changed: 113 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,9 @@ You can run the integration test server by executing `spicedb serve-testing` or
2525

2626
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.
2727

28-
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.
28+
**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.
29+
30+
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.
2931

3032
<Callout type="warning">
3133
**Warning:**
@@ -38,9 +40,24 @@ Instead, we recommend using [zed's explain flag] for this purpose.
3840

3941
</Callout>
4042

41-
Configuring this header is done by setting the header `io.spicedb.requestdebuginfo` to the string `true`.
43+
To request debug information, set the header `io.spicedb.requestdebuginfo` to `1`.
44+
45+
<Callout type="info">
46+
**Note:** In SpiceDB v1.30.0+, this header still works but the trace data is
47+
returned in the response body (`debugTrace` field) rather than the trailer.
48+
The trailer `io.spicedb.respmeta.debuginfo` will contain a message indicating
49+
to check the response body instead.
50+
</Callout>
51+
52+
#### Example
53+
54+
Using the `zed` CLI with the `--explain` flag (recommended):
4255

43-
The response will include a trailer, `io.spicedb.respmeta.debuginfo`, with a JSON-encoded tree.
56+
```sh
57+
zed permission check --explain document:firstdoc view user:fred
58+
```
59+
60+
This will print a visual tree of the permission check trace.
4461

4562
## Playground
4663

@@ -150,15 +167,105 @@ project:docs#admin:
150167

151168
## Check Tracing
152169

170+
**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.
171+
153172
SpiceDB supports tracing of check requests to view the path(s) taken to compute the result, as well as timing information.
154173

155-
Request tracing information by setting `with_tracing: true` in the request message and the information will be found in the response message.
174+
To request tracing information, set `withTracing: true` in the request message. The trace data will be returned in the response message.
175+
176+
**Key differences from the header-based approach:**
177+
178+
- More structured and easier to parse programmatically
179+
- Preferred for modern integrations
156180

157181
<Callout type="warning">
158-
**Warning:** In versions older than v1.31.0, request tracing information via a
159-
header and the information will be found in the response footer as JSON.
182+
**Warning:** In versions older than v1.30.0, you must request tracing
183+
information via a header, and the trace data will be returned in the response
184+
trailer as JSON.
160185
</Callout>
161186

187+
#### Example Request/Response
188+
189+
**Request** (using grpcurl):
190+
191+
```sh
192+
grpcurl \
193+
-H "Authorization: Bearer your-token-here" \
194+
-d '{
195+
"resource": {"objectType": "document", "objectId": "firstdoc"},
196+
"permission": "view",
197+
"subject": {"object": {"objectType": "user", "objectId": "fred"}},
198+
"withTracing": true
199+
}' \
200+
your-spicedb-instance:443 \
201+
authzed.api.v1.PermissionsService/CheckPermission
202+
```
203+
204+
**Response**:
205+
206+
```json
207+
{
208+
"permissionship": "PERMISSIONSHIP_HAS_PERMISSION",
209+
"checkedAt": {
210+
"token": "GhUKEzE3MDYxMTIwMDAwMDAwMDAwMDA="
211+
},
212+
"debugTrace": {
213+
"check": {
214+
"resource": {
215+
"objectType": "document",
216+
"objectId": "firstdoc"
217+
},
218+
"permission": "view",
219+
"permissionType": "PERMISSION_TYPE_PERMISSION",
220+
"subject": {
221+
"object": {
222+
"objectType": "user",
223+
"objectId": "fred"
224+
}
225+
},
226+
"result": "PERMISSIONSHIP_HAS_PERMISSION",
227+
"duration": "0.000125s",
228+
"subProblems": {
229+
"traces": [
230+
{
231+
"resource": {
232+
"objectType": "document",
233+
"objectId": "firstdoc"
234+
},
235+
"permission": "reader",
236+
"permissionType": "PERMISSION_TYPE_RELATION",
237+
"subject": {
238+
"object": {
239+
"objectType": "user",
240+
"objectId": "fred"
241+
}
242+
},
243+
"result": "PERMISSIONSHIP_HAS_PERMISSION",
244+
"duration": "0.000045s"
245+
}
246+
]
247+
}
248+
},
249+
"schemaUsed": "definition document {\n relation reader: user\n permission view = reader\n}\n\ndefinition user {}"
250+
}
251+
}
252+
```
253+
254+
The `debugTrace` field contains a `DebugInformation` object with:
255+
256+
- `check`: A `CheckDebugTrace` object containing the trace tree
257+
- `schemaUsed`: The schema that was used for the check
258+
259+
Each `CheckDebugTrace` includes:
260+
261+
- `resource`: The resource being checked
262+
- `permission`: The permission or relation name
263+
- `permissionType`: Whether it's a `PERMISSION_TYPE_PERMISSION` or `PERMISSION_TYPE_RELATION`
264+
- `subject`: The subject of the check
265+
- `result`: The permissionship result
266+
- `duration`: Time spent on this check (as a Duration string, e.g., "0.000125s")
267+
- `subProblems`: Contains `traces` array with nested `CheckDebugTrace` objects, or `wasCachedResult: true` if cached
268+
162269
## Zed
163270

164271
### Zed Validate

‎wordlist.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
personal_ws-1.1 en 654
1+
personal_ws-1.1 en 655
22
ABAC
33
ACKing
44
ACL
@@ -440,6 +440,7 @@ goroutines
440440
governance
441441
gpg
442442
grpc
443+
grpcurl
443444
grpcutil
444445
hashlib
445446
heredoc

0 commit comments

Comments
 (0)