From 63e50e525f2342e673228018d8b6e021fdbd741b Mon Sep 17 00:00:00 2001 From: Maria Ines Parnisari Date: Thu, 7 Nov 2024 19:42:29 -0800 Subject: [PATCH 1/5] docs: improve docs on caching --- .../getting-started/production-best-practices.mdx | 4 +++- .../getting-started/tuples-api-best-practices.mdx | 11 +++++++++-- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/content/getting-started/production-best-practices.mdx b/docs/content/getting-started/production-best-practices.mdx index c98b92c39..fc7b9bb3b 100644 --- a/docs/content/getting-started/production-best-practices.mdx +++ b/docs/content/getting-started/production-best-practices.mdx @@ -29,7 +29,9 @@ The following list outlines best practices for running OpenFGA in a production e We recommend: -1. Turn on caching via the flag `--check-query-cache-enabled`. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. (The TTL is configurable). +1. Turn on caching in Check API via flags. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. + 1. `--check-query-cache-enabled`. This caches Check sub-problems for a specified TTL (default of 10 seconds). For example, if you have a relation `define viewer: owner or editor`, and the query is `Check(user:anne, viewer, doc:1)`, we'll evaluate the `owner` relation and the `editor` relation and cache both results: `(user:anne, viewer, doc:1) -> allowed=true` and `(user:anne, owner, doc:1) -> allowed=true`. The cache is stored in-memory; the cached values are overwritten on every change in the result, and cleared after the configured TTL. + 2. `--check-iterator-cache-enabled`. This caches rows from the database, for a specified TTL (default of 10 seconds). 2. Prefer having a small pool of servers with high capacity (memory and CPU cores) instead of a big pool of servers, to increase cache hit ratios and simplify pool management. 3. Turn on metrics collection via the flags `--metrics-enabled` and `--datastore-metrics-enabled`. This will allow you to debug issues. 4. Turn on tracing via the flag `--trace-enabled`, but set sampling ratio to a low value, for example `--trace-sample-ratio=0.3`. This will allow you to debug issues without overwhelming the tracing server. However, keep in mind that enabling tracing comes with a slight performance cost. diff --git a/docs/content/getting-started/tuples-api-best-practices.mdx b/docs/content/getting-started/tuples-api-best-practices.mdx index bc3572869..d7a0a32b1 100644 --- a/docs/content/getting-started/tuples-api-best-practices.mdx +++ b/docs/content/getting-started/tuples-api-best-practices.mdx @@ -19,7 +19,8 @@ import { The following list outlines some guidelines and best practices for using : - Do not store Personal Identifiable Information in tuples -- Always specify authorization model ID whenever possible +- Always specify authorization model ID in requests +- Always specify the desired consistency in requests ## Do Not Store Personal Identifiable Information in Tuples @@ -29,7 +30,7 @@ You can use any string for user and object identifiers, however you should not i The documentation and samples uses first names and simple ids to illustrate easy-to-follow examples. ::: -## Always specify authorization model ID whenever possible +## Always specify authorization model ID in requests It is strongly recommended that authorization model ID be specified in your Relationship Queries (such as [Check](./perform-check.mdx) and [ListObjects](../interacting/relationship-queries.mdx#listobjects)) and Relationship Commands (such as [Write](./update-tuples.mdx)). @@ -37,6 +38,12 @@ Specifying authorization model ID in API calls have the following advantages: 1. Better performance as will not need to perform a database query to get the latest authorization model ID. 2. Allows consistent behavior in your production system until you are ready to switch to the new model. +## Always specify the desired consistency in requests + +It is strongly recommended that you specify the `Consistency` value in each individual request, depending on whether you prefer speed (MINIMIZE_LATENCY) or correctness (MAXIMIZE_CONSISTENCY). The default is MINIMIZE_LATENCY. + +In addition, if speed matters to you, we recommend that you follow [Production Best Practices](./production-best-practices.mdx). + ## Related Sections Date: Fri, 8 Nov 2024 15:01:04 -0800 Subject: [PATCH 2/5] update --- docs/content/getting-started/production-best-practices.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/getting-started/production-best-practices.mdx b/docs/content/getting-started/production-best-practices.mdx index fc7b9bb3b..db33cec2c 100644 --- a/docs/content/getting-started/production-best-practices.mdx +++ b/docs/content/getting-started/production-best-practices.mdx @@ -31,7 +31,7 @@ We recommend: 1. Turn on caching in Check API via flags. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. 1. `--check-query-cache-enabled`. This caches Check sub-problems for a specified TTL (default of 10 seconds). For example, if you have a relation `define viewer: owner or editor`, and the query is `Check(user:anne, viewer, doc:1)`, we'll evaluate the `owner` relation and the `editor` relation and cache both results: `(user:anne, viewer, doc:1) -> allowed=true` and `(user:anne, owner, doc:1) -> allowed=true`. The cache is stored in-memory; the cached values are overwritten on every change in the result, and cleared after the configured TTL. - 2. `--check-iterator-cache-enabled`. This caches rows from the database, for a specified TTL (default of 10 seconds). + 2. `--check-iterator-cache-enabled`. This caches some tuples from the database, for a specified TTL (default of 10 seconds). 2. Prefer having a small pool of servers with high capacity (memory and CPU cores) instead of a big pool of servers, to increase cache hit ratios and simplify pool management. 3. Turn on metrics collection via the flags `--metrics-enabled` and `--datastore-metrics-enabled`. This will allow you to debug issues. 4. Turn on tracing via the flag `--trace-enabled`, but set sampling ratio to a low value, for example `--trace-sample-ratio=0.3`. This will allow you to debug issues without overwhelming the tracing server. However, keep in mind that enabling tracing comes with a slight performance cost. From cd2d04973451465e03325b46499e7381137c14e9 Mon Sep 17 00:00:00 2001 From: Maria Ines Parnisari Date: Sat, 9 Nov 2024 18:43:23 -0800 Subject: [PATCH 3/5] revamp --- .../production-best-practices.mdx | 4 +--- .../tuples-api-best-practices.mdx | 4 ++-- docs/content/interacting/consistency.mdx | 17 ++++++++++------- 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/content/getting-started/production-best-practices.mdx b/docs/content/getting-started/production-best-practices.mdx index db33cec2c..88a655fe7 100644 --- a/docs/content/getting-started/production-best-practices.mdx +++ b/docs/content/getting-started/production-best-practices.mdx @@ -29,9 +29,7 @@ The following list outlines best practices for running OpenFGA in a production e We recommend: -1. Turn on caching in Check API via flags. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. - 1. `--check-query-cache-enabled`. This caches Check sub-problems for a specified TTL (default of 10 seconds). For example, if you have a relation `define viewer: owner or editor`, and the query is `Check(user:anne, viewer, doc:1)`, we'll evaluate the `owner` relation and the `editor` relation and cache both results: `(user:anne, viewer, doc:1) -> allowed=true` and `(user:anne, owner, doc:1) -> allowed=true`. The cache is stored in-memory; the cached values are overwritten on every change in the result, and cleared after the configured TTL. - 2. `--check-iterator-cache-enabled`. This caches some tuples from the database, for a specified TTL (default of 10 seconds). +1. Turn on caching in Check API via flags. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. Please see [Cache Expiration](../interacting/consistency.mdx#cache-expiration) for details on the flags. 2. Prefer having a small pool of servers with high capacity (memory and CPU cores) instead of a big pool of servers, to increase cache hit ratios and simplify pool management. 3. Turn on metrics collection via the flags `--metrics-enabled` and `--datastore-metrics-enabled`. This will allow you to debug issues. 4. Turn on tracing via the flag `--trace-enabled`, but set sampling ratio to a low value, for example `--trace-sample-ratio=0.3`. This will allow you to debug issues without overwhelming the tracing server. However, keep in mind that enabling tracing comes with a slight performance cost. diff --git a/docs/content/getting-started/tuples-api-best-practices.mdx b/docs/content/getting-started/tuples-api-best-practices.mdx index d7a0a32b1..d1a483694 100644 --- a/docs/content/getting-started/tuples-api-best-practices.mdx +++ b/docs/content/getting-started/tuples-api-best-practices.mdx @@ -20,7 +20,7 @@ The following list outlines some guidelines and best practices for using will not need to perform a database query to get the latest authorization model ID. 2. Allows consistent behavior in your production system until you are ready to switch to the new model. -## Always specify the desired consistency in requests +## Specify the desired consistency in requests It is strongly recommended that you specify the `Consistency` value in each individual request, depending on whether you prefer speed (MINIMIZE_LATENCY) or correctness (MAXIMIZE_CONSISTENCY). The default is MINIMIZE_LATENCY. diff --git a/docs/content/interacting/consistency.mdx b/docs/content/interacting/consistency.mdx index 9c6a40d61..39a449e98 100644 --- a/docs/content/interacting/consistency.mdx +++ b/docs/content/interacting/consistency.mdx @@ -51,19 +51,22 @@ if (date_modified + cache_time_to_live_period > Date.now()) { ## Cache expiration - cache is disabled by default. When not enabled, all queries will have strong consistency regardless of the consistency mode specified. + caching is disabled by default. When caching is disabled, all queries will have strong consistency regardless of the consistency mode specified. When caching is enabled, the cache will be used for queries with `MINIMIZE_LATENCY` consistency mode. You can use the following parameters to configure 's cache: -| Name | Description | -|-------------------------|---------------------------------------------------------------------------------| -| check-query-cache | Enables caching (default = false) | -| check-query-cache-limit | Configures the number of items that will be kept in the cache (default = 10000) | -| check-query-cache-ttl | Specifies the time that items will be kept in the cache (default = 10s) | +| Name | Description | +|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| check-cache-limit | Configures the number of items that will be kept in the in-memory cache used to resolve Check queries (default = 1000) | +| check-query-cache-enabled | Enables in-memory caching of Check subproblems (default = false). For example, if you have a relation `define viewer: owner or editor`, and the query is `Check(user:anne, viewer, doc:1)`, we'll evaluate the `owner` relation and the `editor` relation and cache both results: `(user:anne, viewer, doc:1) -> allowed=true` and `(user:anne, owner, doc:1) -> allowed=true`. | +| check-query-cache-ttl | Specifies the time that items will be kept in the cache of Check subproblems (default = 10s) | +| check-iterator-cache-enabled | Enables in-memory caching of database iterators. Each iterator is the result of a database query, for example, usersets related to a specific object, or objects related to a specific user, up to a certain number of tuples per iterator (default = false) | +| check-iterator-cache-max-results | Configures the number of tuples that will be stored for each database iterator (default = 10000) | +| check-iterator-cache-ttl | Specifies the time that items will be kept in the cache of database iterators (default = 10s) | Learn how to [configure ](../getting-started/setup-openfga/configure-openfga.mdx). -Currently, the cache is used by Check and partially in ListObjects. It will be implemented it for other query endpoints in the future. +Currently, the cache is used by Check and partially in ListObjects. It will be implemented for other query endpoints in the future. ## Future work From 6d18518349cfbaedb279c8a85c835f9ff446296c Mon Sep 17 00:00:00 2001 From: Maria Ines Parnisari Date: Fri, 15 Nov 2024 17:55:35 -0800 Subject: [PATCH 4/5] update --- docs/content/concepts.mdx | 2 +- docs/content/getting-started/production-best-practices.mdx | 2 +- docs/content/getting-started/tuples-api-best-practices.mdx | 2 +- docs/content/interacting/consistency.mdx | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/content/concepts.mdx b/docs/content/concepts.mdx index d790a49c2..85212a42d 100644 --- a/docs/content/concepts.mdx +++ b/docs/content/concepts.mdx @@ -624,7 +624,7 @@ For example, the following returns all the users of type `user` that have the `v }} /> -For more information, see the the [ListUsers API Reference](/api/service#Relationship%20Queries/ListUsers). +For more information, see the [ListUsers API Reference](/api/service#Relationship%20Queries/ListUsers).
diff --git a/docs/content/getting-started/production-best-practices.mdx b/docs/content/getting-started/production-best-practices.mdx index 88a655fe7..14b7df5fe 100644 --- a/docs/content/getting-started/production-best-practices.mdx +++ b/docs/content/getting-started/production-best-practices.mdx @@ -29,7 +29,7 @@ The following list outlines best practices for running OpenFGA in a production e We recommend: -1. Turn on caching in Check API via flags. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. Please see [Cache Expiration](../interacting/consistency.mdx#cache-expiration) for details on the flags. +1. Turn on in-memory caching in Check API via flags. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. Please see [Cache Expiration](../interacting/consistency.mdx#cache-expiration) for details on the flags. 2. Prefer having a small pool of servers with high capacity (memory and CPU cores) instead of a big pool of servers, to increase cache hit ratios and simplify pool management. 3. Turn on metrics collection via the flags `--metrics-enabled` and `--datastore-metrics-enabled`. This will allow you to debug issues. 4. Turn on tracing via the flag `--trace-enabled`, but set sampling ratio to a low value, for example `--trace-sample-ratio=0.3`. This will allow you to debug issues without overwhelming the tracing server. However, keep in mind that enabling tracing comes with a slight performance cost. diff --git a/docs/content/getting-started/tuples-api-best-practices.mdx b/docs/content/getting-started/tuples-api-best-practices.mdx index d1a483694..a501ceee8 100644 --- a/docs/content/getting-started/tuples-api-best-practices.mdx +++ b/docs/content/getting-started/tuples-api-best-practices.mdx @@ -40,7 +40,7 @@ Specifying authorization model ID in API calls have the following advantages: ## Specify the desired consistency in requests -It is strongly recommended that you specify the `Consistency` value in each individual request, depending on whether you prefer speed (MINIMIZE_LATENCY) or correctness (MAXIMIZE_CONSISTENCY). The default is MINIMIZE_LATENCY. +It is strongly recommended that you specify the `Consistency` value in each individual request. Please see [Query Consistency Modes](../interacting/consistency.mdx) for more details. In addition, if speed matters to you, we recommend that you follow [Production Best Practices](./production-best-practices.mdx). diff --git a/docs/content/interacting/consistency.mdx b/docs/content/interacting/consistency.mdx index 39a449e98..f041707b9 100644 --- a/docs/content/interacting/consistency.mdx +++ b/docs/content/interacting/consistency.mdx @@ -24,9 +24,9 @@ When querying using Read or | Name | Description | |-----------------------------|---------------------------------------------------------------------------------------------------------------| | MINIMIZE_LATENCY (default) | will serve queries from the cache when possible | -| HIGHER_CONSISTENCY | will skip the cache and query the the database directly | +| HIGHER_CONSISTENCY | will skip the cache and query the database directly | -If you write a tuple and you immediately make a check on a relation affected by that tuple using `MINIMIZE_LATENCY`, the tuple change might not be taken in consideration if serves the result from the cache. +If you write a tuple and you immediately make a Check on a relation affected by that tuple using `MINIMIZE_LATENCY`, the tuple change might not be taken in consideration if serves the result from the cache. ## When to use higher consistency From 6b2ab27698e44ea35ba2f3ade8cbf07126ac6c70 Mon Sep 17 00:00:00 2001 From: Maria Ines Parnisari Date: Tue, 26 Nov 2024 14:32:02 -0800 Subject: [PATCH 5/5] remove the consistency best practice --- .../getting-started/tuples-api-best-practices.mdx | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/docs/content/getting-started/tuples-api-best-practices.mdx b/docs/content/getting-started/tuples-api-best-practices.mdx index a501ceee8..bc3572869 100644 --- a/docs/content/getting-started/tuples-api-best-practices.mdx +++ b/docs/content/getting-started/tuples-api-best-practices.mdx @@ -19,8 +19,7 @@ import { The following list outlines some guidelines and best practices for using : - Do not store Personal Identifiable Information in tuples -- Always specify authorization model ID in requests -- Specify the desired consistency in requests +- Always specify authorization model ID whenever possible ## Do Not Store Personal Identifiable Information in Tuples @@ -30,7 +29,7 @@ You can use any string for user and object identifiers, however you should not i The documentation and samples uses first names and simple ids to illustrate easy-to-follow examples. ::: -## Always specify authorization model ID in requests +## Always specify authorization model ID whenever possible It is strongly recommended that authorization model ID be specified in your Relationship Queries (such as [Check](./perform-check.mdx) and [ListObjects](../interacting/relationship-queries.mdx#listobjects)) and Relationship Commands (such as [Write](./update-tuples.mdx)). @@ -38,12 +37,6 @@ Specifying authorization model ID in API calls have the following advantages: 1. Better performance as will not need to perform a database query to get the latest authorization model ID. 2. Allows consistent behavior in your production system until you are ready to switch to the new model. -## Specify the desired consistency in requests - -It is strongly recommended that you specify the `Consistency` value in each individual request. Please see [Query Consistency Modes](../interacting/consistency.mdx) for more details. - -In addition, if speed matters to you, we recommend that you follow [Production Best Practices](./production-best-practices.mdx). - ## Related Sections