Operations & Usage
Understand the operations_consumed metric and how it can help you optimize your FGA usage.
WorkOS Fine-Grained Authorization (FGA) empowers developers to design custom authorization models tailored to their specific needs using Access Control Lists (ACLs). In FGA, ACLs can inherit from one another through explicit connections or custom inheritance rules (see inheritance rules documentation). However, the flexibility of these models can complicate capacity planning for FGA quota.
FGA includes the operations_consumed metric in select API responses to provide visibility into quota consumption. This metric measures the computational cost of access checks, queries, and warrant transactions, offering developers valuable insights into how their authorization models affect quota usage.
Complex models with deeply nested data or intricate inheritance rules can significantly increase the computational cost of FGA transactions, making it critical to design models thoughtfully. By understanding the impact of these factors, developers can make informed decisions to balance functionality and efficiency.
This article breaks down the purpose of the operations_consumed metric, how it works, and strategies for optimizing FGA usage to better manage quota consumption.
operations_consumed is a metric that quantifies the number of computational operations performed during an ACL check or query in FGA. These operations include sub-tree checks and partial queries that are required to return the response. By tracking this value, FGA provides visibility into quota consumption, enabling developers to:
- Understand the cost of their authorization checks.
- Optimize their schema for better performance.
- Ensure efficient usage within the provided quota.
FGA performs access checks by traversing the ACL graph. The ACL graph is defined by warrant connections that are bridged by the inheritance rules defined in your schema. These operations include:
- Edge Traversals: Verifying ACL connectivity through adjacent resources using warrant relations.
- Inheritance Rules: Evaluating relationships based on inherited connections in your schema.
- Consistency Operations: Determining whether fully consistent or eventually consistent results are required.
In addition to schema complexity, the number of operations required to evaluate an access check also depends on sub-tree caching. Fully consistent checks inherently rely less on caching than eventually consistent checks. Eventually consistent checks have less strict cache policies, reducing the number of required sub-tree evaluations. However, requests for eventual consistency are not guaranteed to be served from cache. As a result, operations_consumed may vary slightly across requests, with the worst-case scenario involving no caching.
FGA handles cached operations as follows:
- A single access check on cached data always counts as one operation.
- Multiple checks on the same cached result within a single transaction each count as one operation.
- Accessing cached sub-trees avoids evaluating the sub-tree, significantly optimizing query execution.
To optimize both performance and cost, it’s essential to use Warrant Tokens (see Warrant Token documentation) effectively and align your schema design with your consistency requirements.
The structure of your ACL graph significantly impacts the operations_consumed metric. Here’s why:
- Nested Graphs: While some nesting is acceptable, deeply nested relationships can significantly increase the complexity of access checks. Each additional layer in the graph requires more operations to resolve access, potentially impacting performance and query efficiency.
- Wide Graphs: Graphs with many/all resources converging on a single node demand more operations per check to resolve access. As your application grows in size and complexity, more connections may focus on a single node. Performance may degrade and usage could increase.
- Sparse or Disjoint Graphs: Sparse graphs, where resources and subjects are minimally connected, consume fewer operations. Disjoint sub-graphs, typically separated by tenant or user, are particularly efficient. Both reduce the traversal scope.
To preserve operations and stay within quota limits, developers can utilize the following strategies:
Divide ACLs into smaller, independent sub-graphs. This approach reduces the traversal depth and isolates computational effort to specific areas of the graph. For example, building disjoint sub-graphs for different tenants that use your application.
Use fully consistent checks only when necessary. Opt for eventually consistent checks to increase the likelihood of cache hits. In practice, developers can avoid fully consistent checks by using Warrant Tokens in API requests.
Store API-generated Warrant Tokens with atomic writes to reuse them for future access checks, minimizing redundant computations. Cached warrant tokens reduce the need to use fully consistent checks.
Avoid building a model with unnecessary nesting, complicated inheritance rules, or wide connections. Streamlining relationships minimizes the number of operations required to resolve an access check.
FGA charges based on operations_consumed usage, encouraging efficient graph design while providing the flexibility to build robust, scalable access control systems. Key benefits include:
- Lower Costs: Reduce quota consumption with optimized graph structures.
- Better Performance: Deliver faster response times for access checks and queries.
- Scalability: Handle larger datasets efficiently without increased resource demands.
By optimizing operations_consumed, developers can create cost-effective, high-performing access control models that scale with their applications.