Skip to content

Commit 024973a

Browse files
ivanauthivanauth
committed
docs: add tracing examples and fix formatting
1 parent 32bfbc7 commit 024973a

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

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

149-
150-
151147
## Reference: `spicedb datastore head`
152148

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

182-
183-
184178
## Reference: `spicedb datastore migrate`
185179

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

223-
224-
225217
## Reference: `spicedb datastore repair`
226218

227219
Executes a repair operation for the datastore
@@ -312,8 +304,6 @@ spicedb datastore repair [flags]
312304
--skip-release-check if true, skips checking for new SpiceDB releases
313305
```
314306

315-
316-
317307
## Reference: `spicedb lsp`
318308

319309
serve language server protocol
@@ -337,20 +327,17 @@ spicedb lsp [flags]
337327
--skip-release-check if true, skips checking for new SpiceDB releases
338328
```
339329

340-
341-
342330
## Reference: `spicedb man`
343331

344332
Generate a man page for SpiceDB.
345-
The output can be redirected to a file and installed to the system:
333+
The output can be redirected to a file and installed to the system:
346334

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

353-
354341
```
355342
spicedb man
356343
```
@@ -363,8 +350,6 @@ spicedb man
363350
--skip-release-check if true, skips checking for new SpiceDB releases
364351
```
365352

366-
367-
368353
## Reference: `spicedb postgres-fdw`
369354

370355
EXPERIMENTAL: Serves a Postgres-compatible interface for querying SpiceDB data using foreign data wrappers. This feature is experimental and subject to change.
@@ -392,8 +377,6 @@ spicedb postgres-fdw [flags]
392377
--skip-release-check if true, skips checking for new SpiceDB releases
393378
```
394379

395-
396-
397380
## Reference: `spicedb serve`
398381

399382
start a SpiceDB server
@@ -580,8 +563,6 @@ spicedb serve [flags]
580563
--skip-release-check if true, skips checking for new SpiceDB releases
581564
```
582565

583-
584-
585566
## Reference: `spicedb serve-testing`
586567

587568
An in-memory spicedb server which serves completely isolated datastores per client-supplied auth token used.
@@ -644,8 +625,6 @@ spicedb serve-testing [flags]
644625
--skip-release-check if true, skips checking for new SpiceDB releases
645626
```
646627

647-
648-
649628
## Reference: `spicedb version`
650629

651630
displays the version of SpiceDB
@@ -667,6 +646,3 @@ spicedb version [flags]
667646
--log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info")
668647
--skip-release-check if true, skips checking for new SpiceDB releases
669648
```
670-
671-
672-

‎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 header and the
159-
information will be found in the response footer as JSON.
182+
**Warning:** In versions older than v1.31.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
@@ -441,6 +441,7 @@ goroutines
441441
governance
442442
gpg
443443
grpc
444+
grpcurl
444445
grpcutil
445446
hashlib
446447
heredoc

0 commit comments

Comments
 (0)