From 70e63e3d93626d41f28d44f96004c884b7514038 Mon Sep 17 00:00:00 2001 From: Joseph Schorr Date: Mon, 30 Dec 2024 11:58:58 -0500 Subject: [PATCH 1/3] Add debug trace support to bulk check API --- authzed/api/v1/debug.proto | 6 ++++++ authzed/api/v1/permission_service.proto | 8 ++++++++ 2 files changed, 14 insertions(+) diff --git a/authzed/api/v1/debug.proto b/authzed/api/v1/debug.proto index 03fc216..b73df56 100644 --- a/authzed/api/v1/debug.proto +++ b/authzed/api/v1/debug.proto @@ -46,6 +46,8 @@ message CheckDebugTrace { } // resource holds the resource on which the Check was performed. + // for batched calls, the object_id field contains a comma-separated list of object IDs + // for all the resources checked in the batch. ObjectReference resource = 1 [ (validate.rules).message.required = true ]; // permission holds the name of the permission or relation on which the Check was performed. @@ -82,6 +84,10 @@ message CheckDebugTrace { // optional_expires_at is the time at which at least one of the relationships used to // compute this result, expires (if any). This is *not* related to the caching window. google.protobuf.Timestamp optional_expires_at = 10; + + // trace_id is a unique identifier for this trace. This identifier is only guanranteed + // to be unique within the same overall Check or CheckBulk operation. + string trace_id = 11; } // CaveatEvalInfo holds information about a caveat expression that was evaluated. diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto index 1c754d5..d55bc1c 100644 --- a/authzed/api/v1/permission_service.proto +++ b/authzed/api/v1/permission_service.proto @@ -421,6 +421,11 @@ message CheckBulkPermissionsRequest { Consistency consistency = 1; repeated CheckBulkPermissionsRequestItem items = 2 [ (validate.rules).repeated .items.message.required = true ]; + + // with_tracing, if true, indicates that each response should include a debug trace. + // This can be useful for debugging and performance analysis, but adds a small amount + // of compute overhead to the request. + bool with_tracing = 3; } message CheckBulkPermissionsRequestItem { @@ -454,6 +459,9 @@ message CheckBulkPermissionsResponseItem { CheckPermissionResponse.Permissionship permissionship = 1 [ (validate.rules).enum = {defined_only: true, not_in: [0]} ]; PartialCaveatInfo partial_caveat_info = 2 [ (validate.rules).message.required = false ]; + + // debug_trace is the debugging trace of this check, if requested. + DebugInformation debug_trace = 3; } // ExpandPermissionTreeRequest returns a tree representing the expansion of all From 54441d02537f8a0f5d602995e65f80e0986042e4 Mon Sep 17 00:00:00 2001 From: Joseph Schorr Date: Mon, 6 Jan 2025 17:13:56 -0500 Subject: [PATCH 2/3] Add `source` field to debug information for better resolution information --- authzed/api/v1/debug.proto | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/authzed/api/v1/debug.proto b/authzed/api/v1/debug.proto index b73df56..bf49e5a 100644 --- a/authzed/api/v1/debug.proto +++ b/authzed/api/v1/debug.proto @@ -85,9 +85,14 @@ message CheckDebugTrace { // compute this result, expires (if any). This is *not* related to the caching window. google.protobuf.Timestamp optional_expires_at = 10; - // trace_id is a unique identifier for this trace. This identifier is only guanranteed + // trace_id is a unique identifier for this trace. This identifier is only guaranteed // to be unique within the same overall Check or CheckBulk operation. string trace_id = 11; + + // source holds the source of the result. It is of the form: + // `:`, where sourcetype can be, among others: + // `spicedb`, `materialize`, etc. + string source = 12; } // CaveatEvalInfo holds information about a caveat expression that was evaluated. From 4b70b0b63af2d3c7cab76d33a2d25ca3b0c2ea56 Mon Sep 17 00:00:00 2001 From: Joseph Schorr Date: Tue, 7 Jan 2025 11:00:41 -0500 Subject: [PATCH 3/3] Clarify trace comments --- authzed/api/v1/debug.proto | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/authzed/api/v1/debug.proto b/authzed/api/v1/debug.proto index bf49e5a..ad06688 100644 --- a/authzed/api/v1/debug.proto +++ b/authzed/api/v1/debug.proto @@ -85,9 +85,15 @@ message CheckDebugTrace { // compute this result, expires (if any). This is *not* related to the caching window. google.protobuf.Timestamp optional_expires_at = 10; - // trace_id is a unique identifier for this trace. This identifier is only guaranteed - // to be unique within the same overall Check or CheckBulk operation. - string trace_id = 11; + // trace_operation_id is a unique identifier for this trace's operation, that will + // be shared for all traces created for the same check operation in SpiceDB. + // + // In cases where SpiceDB performs automatic batching of subproblems, this ID can be used + // to correlate work that was shared across multiple traces. + // + // This identifier is generated by SpiceDB, is to be considered opaque to the caller + // and only guaranteed to be unique within the same overall Check or CheckBulk operation. + string trace_operation_id = 11; // source holds the source of the result. It is of the form: // `:`, where sourcetype can be, among others: