Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: improve docs on caching #886

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

docs: improve docs on caching #886

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
63e50e5
docs: improve docs on caching
miparnisari Nov 8, 2024
e2b8b2f
update
miparnisari Nov 8, 2024
70682be
Merge remote-tracking branch 'origin/main' into caching-docs
miparnisari Nov 8, 2024
cd2d049
revamp
miparnisari Nov 10, 2024
6d18518
update
miparnisari Nov 16, 2024
98bc858
Merge remote-tracking branch 'origin/main' into caching-docs
miparnisari Nov 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/content/concepts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

</details>
<details>
Expand Down
2 changes: 1 addition & 1 deletion docs/content/getting-started/production-best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ 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 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.
Expand Down
11 changes: 9 additions & 2 deletions docs/content/getting-started/tuples-api-best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ import {
The following list outlines some guidelines and best practices for using <ProductName format={ProductNameFormat.ShortForm}/>:

- Do not store Personal Identifiable Information in tuples
- Always specify authorization model ID whenever possible
- Always specify authorization model ID in requests
- Specify the desired consistency in requests
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we link "consistency" to the relevant part in the doc? I would imagine people might not know what that is.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This bullet list is the titles of the sections below. I added the link to what consistency is down below 👍


## Do Not Store Personal Identifiable Information in Tuples

Expand All @@ -29,14 +30,20 @@ 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)).

Specifying authorization model ID in API calls have the following advantages:
1. Better performance as <ProductName format={ProductNameFormat.ShortForm}/> 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

<RelatedSection
Expand Down
21 changes: 12 additions & 9 deletions docs/content/interacting/consistency.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ When querying <ProductName format={ProductNameFormat.ShortForm}/> using Read or
| Name | Description |
|-----------------------------|---------------------------------------------------------------------------------------------------------------|
| MINIMIZE_LATENCY (default) | <ProductName format={ProductNameFormat.ShortForm}/> will serve queries from the cache when possible |
| HIGHER_CONSISTENCY | <ProductName format={ProductNameFormat.ShortForm}/> will skip the cache and query the the database directly |
| HIGHER_CONSISTENCY | <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/> serves the result from the cache.

## When to use higher consistency

Expand All @@ -51,19 +51,22 @@ if (date_modified + cache_time_to_live_period > Date.now()) {

## Cache expiration

<ProductName format={ProductNameFormat.ShortForm}/> cache is disabled by default. When not enabled, all queries will have strong consistency regardless of the consistency mode specified.
<ProductName format={ProductNameFormat.ShortForm}/> 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 <ProductName format={ProductNameFormat.ShortForm}/>'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 <ProductName format={ProductNameFormat.ShortForm}/>](../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

Expand Down
Loading