Merge pull request #127 from josephschorr/bulk-check-debug

Add debug trace support to bulk check API

Author: josephschorr

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,21 @@ 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_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:
+  // `<sourcetype>:<sourceid>`, where sourcetype can be, among others:
+  // `spicedb`, `materialize`, etc.
+  string source = 12;
 }
 
 // CaveatEvalInfo holds information about a caveat expression that was evaluated.

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