From aadbf4aabf3f454e60b725a6c36a7dd84e399c10 Mon Sep 17 00:00:00 2001 From: Kyle Brown Date: Tue, 3 Nov 2026 14:44:30 -0700 Subject: [PATCH] docs: explain logical checks for SpiceDB compute sizing Signed-off-by: Kyle Brown --- app/spicedb/ops/load-testing/page.mdx | 5 +++++ app/spicedb/ops/observability/page.mdx | 2 ++ 2 files changed, 7 insertions(+) diff --git a/app/spicedb/ops/load-testing/page.mdx b/app/spicedb/ops/load-testing/page.mdx index a99bd949..9c5004df 100644 --- a/app/spicedb/ops/load-testing/page.mdx +++ b/app/spicedb/ops/load-testing/page.mdx @@ -361,6 +361,11 @@ By far, the most common sign you need to scale your datastore up or out is high ### Scaling the SpiceDB Compute +Use logical checks per second as the baseline workload measure when sizing SpiceDB compute. +A logical check represents an individual permission check: a `CheckPermission` request counts as one, while a `CheckBulkPermissions` request containing 100 checks counts as 100. +Monitor the rate of the `spicedb_services_logical_checks_total` counter across your deployment's replicas, and use representative load tests to determine the compute needed to meet your latency requirements. +Compute cost per logical check varies with schema complexity, relationship fanout, consistency settings, and cache utilization. + Like the datastore, it’s important to scale if CPU utilization is high; however, since SpiceDB is such a performance sensitive workload, we've seen significant performance gains from scaling out CPU in nodes that we’re experiencing less than 30% CPU utilization. ## How Authzed helps with Load Testing SpiceDB diff --git a/app/spicedb/ops/observability/page.mdx b/app/spicedb/ops/observability/page.mdx index 1a9a6a68..bc41f61a 100644 --- a/app/spicedb/ops/observability/page.mdx +++ b/app/spicedb/ops/observability/page.mdx @@ -20,6 +20,8 @@ A [Prometheus metrics endpoint][prom-endpoint] can be found on this server at th Available metrics include operational information about the Go runtime and serving metrics for any servers that are enabled. +For guidance on using the `spicedb_services_logical_checks_total` counter to size SpiceDB compute, see [Scaling the SpiceDB Compute](/spicedb/ops/load-testing#scaling-the-spicedb-compute). + A [Grafana dashboard][grafana-dashboard] is available for visualizing these metrics. [command]: /spicedb/concepts/commands