From 25da33289b027bb31d990708273c29a73860670f Mon Sep 17 00:00:00 2001 From: Johan Fylling Date: Tue, 29 Oct 2024 16:06:11 +0100 Subject: [PATCH] Adding docs Signed-off-by: Johan Fylling --- cmd/flags.go | 3 +- docs/content/cli.md | 51 ++++++++++++++++-------------- docs/content/policy-performance.md | 16 ++++++++++ 3 files changed, 44 insertions(+), 26 deletions(-) diff --git a/cmd/flags.go b/cmd/flags.go index e4cb12e148..c0e65b5219 100644 --- a/cmd/flags.go +++ b/cmd/flags.go @@ -166,8 +166,7 @@ func addV1CompatibleFlag(fs *pflag.FlagSet, v1Compatible *bool, value bool) { } func addReadAstValuesFromStoreFlag(fs *pflag.FlagSet, readAstValuesFromStore *bool, value bool) { - // FIXME: naming? - fs.BoolVar(readAstValuesFromStore, "read-ast-values", value, "read AST values from store") + fs.BoolVar(readAstValuesFromStore, "optimize-store-for-read-speed", value, "optimize default in-memory store for read speed. Has possible negative impact on memory footprint and write speed. See https://www.openpolicyagent.org/docs/latest/policy-performance/#storage-optimization for more details.") } func addE2EFlag(fs *pflag.FlagSet, e2e *bool, value bool) { diff --git a/docs/content/cli.md b/docs/content/cli.md index 668f06db0f..ee040c9640 100755 --- a/docs/content/cli.md +++ b/docs/content/cli.md @@ -40,30 +40,31 @@ opa bench [flags] ### Options ``` - --benchmem report memory allocations with benchmark results (default true) - -b, --bundle string set bundle file(s) or directory path(s). This flag can be repeated. - -c, --config-file string set path of configuration file - --count int number of times to repeat each benchmark (default 1) - -d, --data string set policy or data file(s). This flag can be repeated. - --e2e run benchmarks against a running OPA server - --fail exits with non-zero exit code on undefined/empty result and errors (default true) - -f, --format {json,pretty,gobench} set output format (default pretty) - -h, --help help for bench - --ignore strings set file and directory names to ignore during loading (e.g., '.*' excludes hidden files) - --import string set query import(s). This flag can be repeated. - -i, --input string set input file path - --metrics report query performance metrics (default true) - --package string set query package - -p, --partial perform partial evaluation - -s, --schema string set schema file path or directory path - --shutdown-grace-period int set the time (in seconds) that the server will wait to gracefully shut down. This flag is valid in 'e2e' mode only. (default 10) - --shutdown-wait-period int set the time (in seconds) that the server will wait before initiating shutdown. This flag is valid in 'e2e' mode only. - --stdin read query from stdin - -I, --stdin-input read input document from stdin - -t, --target {rego,wasm} set the runtime to exercise (default rego) - -u, --unknowns stringArray set paths to treat as unknown during partial evaluation (default [input]) - --v0-compatible opt-in to OPA features and behaviors prior to the OPA v1.0 release. Takes precedence over --v1-compatible - --v1-compatible opt-in to OPA features and behaviors that are enabled by default in OPA v1.0 + --benchmem report memory allocations with benchmark results (default true) + -b, --bundle string set bundle file(s) or directory path(s). This flag can be repeated. + -c, --config-file string set path of configuration file + --count int number of times to repeat each benchmark (default 1) + -d, --data string set policy or data file(s). This flag can be repeated. + --e2e run benchmarks against a running OPA server + --fail exits with non-zero exit code on undefined/empty result and errors (default true) + -f, --format {json,pretty,gobench} set output format (default pretty) + -h, --help help for bench + --ignore strings set file and directory names to ignore during loading (e.g., '.*' excludes hidden files) + --import string set query import(s). This flag can be repeated. + -i, --input string set input file path + --metrics report query performance metrics (default true) + --optimize-store-for-read-speed optimize default in-memory store for read speed. Has possible negative impact on memory footprint and write speed. See https://www.openpolicyagent.org/docs/latest/policy-performance/#storage-optimization for more details. + --package string set query package + -p, --partial perform partial evaluation + -s, --schema string set schema file path or directory path + --shutdown-grace-period int set the time (in seconds) that the server will wait to gracefully shut down. This flag is valid in 'e2e' mode only. (default 10) + --shutdown-wait-period int set the time (in seconds) that the server will wait before initiating shutdown. This flag is valid in 'e2e' mode only. + --stdin read query from stdin + -I, --stdin-input read input document from stdin + -t, --target {rego,wasm} set the runtime to exercise (default rego) + -u, --unknowns stringArray set paths to treat as unknown during partial evaluation (default [input]) + --v0-compatible opt-in to OPA features and behaviors prior to the OPA v1.0 release. Takes precedence over --v1-compatible + --v1-compatible opt-in to OPA features and behaviors that are enabled by default in OPA v1.0 ``` ____ @@ -556,6 +557,7 @@ opa eval [flags] --instrument enable query instrumentation metrics (implies --metrics) --metrics report query performance metrics -O, --optimize int set optimization level + --optimize-store-for-read-speed optimize default in-memory store for read speed. Has possible negative impact on memory footprint and write speed. See https://www.openpolicyagent.org/docs/latest/policy-performance/#storage-optimization for more details. --package string set query package -p, --partial perform partial evaluation --pretty-limit int set limit after which pretty output gets truncated (default 80) @@ -913,6 +915,7 @@ opa run [flags] --log-timestamp-format string set log timestamp format (OPA_LOG_TIMESTAMP_FORMAT environment variable) -m, --max-errors int set the number of errors to allow before compilation fails early (default 10) --min-tls-version {1.0,1.1,1.2,1.3} set minimum TLS version to be used by OPA's server (default 1.2) + --optimize-store-for-read-speed optimize default in-memory store for read speed. Has possible negative impact on memory footprint and write speed. See https://www.openpolicyagent.org/docs/latest/policy-performance/#storage-optimization for more details. --pprof enables pprof endpoints --ready-timeout int wait (in seconds) for configured plugins before starting server (value <= 0 disables ready check) --scope string scope to use for bundle signature verification diff --git a/docs/content/policy-performance.md b/docs/content/policy-performance.md index 3152d1ee3b..4b170ef24f 100644 --- a/docs/content/policy-performance.md +++ b/docs/content/policy-performance.md @@ -975,6 +975,22 @@ into call sites. In addition, more aggressive inlining is applied within rules. [copy propagation](https://en.wikipedia.org/wiki/Copy_propagation) and inlining of certain negated statements that would otherwise generate support rules. +## Storage Optimization + +### In-Memory Store Read Optimization + +During normal operation, data values read from storage are converted to an AST representation that is used during policy evaluation. +This conversion can be expensive both in execution time and in memory usage, especially for large data values. +The default in-memory store can be configured to optimize for read speed by precomputing the AST representation of data values during storage write operations. +This removes the time spent converting raw data values to AST during policy evaluation, improving performance. + +The memory footprint of the store will increase, as processed AST values generally take up more space in memory than the corresponding raw data values, but overall memory usage of OPA might remain more stable over time, as pre-converted data is shared across evaluations and isn't recomputed for each evaluation, which can cause spikes in memory usage. +Storage write operations will be slower due to the additional processing required to precompute the AST representation of data values. This can impact startup time and bundle loading/updates, especially for large data values. + +This feature can be enabled for `opa run`, `opa eval`, and `opa bench` by setting the `--optimize-store-for-read-speed` flag. + +Users are recommended to do performance testing to determine the optimal configuration for their use case. + ## Key Takeaways For high-performance use cases: