From f1228663ff631ea95ef7d464de6efa898fbd430a Mon Sep 17 00:00:00 2001 From: Rohit Agrawal Date: Wed, 25 Dec 2024 05:42:26 -0800 Subject: [PATCH] docs: clarify the docs on runtime_filter (#37788) ## Description This PR adds some more description around `use_independent_randomness` to make it more user-friendly and clarify other fields. Screenshot 2024-12-23 at 01 20 20 --- **Commit Message:** docs: clarify the docs on runtime_filter **Additional Description:** Added some more description around `use_independent_randomness` to make it more user-friendly. **Risk Level:** Very Low **Testing:** N/A **Docs Changes:** N/A **Release Notes:** N/A --------- Signed-off-by: Rohit Agrawal --- api/envoy/config/accesslog/v3/accesslog.proto | 45 ++++++++++--------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/api/envoy/config/accesslog/v3/accesslog.proto b/api/envoy/config/accesslog/v3/accesslog.proto index 5599f8082d33..5f8c3e36bd4a 100644 --- a/api/envoy/config/accesslog/v3/accesslog.proto +++ b/api/envoy/config/accesslog/v3/accesslog.proto @@ -152,35 +152,38 @@ message TraceableFilter { "envoy.config.filter.accesslog.v2.TraceableFilter"; } -// Filters for random sampling of requests. +// Filters requests based on runtime-configurable sampling rates. message RuntimeFilter { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.accesslog.v2.RuntimeFilter"; - // Runtime key to get an optional overridden numerator for use in the - // ``percent_sampled`` field. If found in runtime, this value will replace the - // default numerator. + // Specifies a key used to look up a custom sampling rate from the runtime configuration. If a value is found for this + // key, it will override the default sampling rate specified in ``percent_sampled``. string runtime_key = 1 [(validate.rules).string = {min_len: 1}]; - // The default sampling percentage. If not specified, defaults to 0% with - // denominator of 100. + // Defines the default sampling percentage when no runtime override is present. If not specified, the default is + // **0%** (with a denominator of 100). type.v3.FractionalPercent percent_sampled = 2; - // By default, sampling pivots on the header - // :ref:`x-request-id` being - // present. If :ref:`x-request-id` - // is present, the filter will consistently sample across multiple hosts based - // on the runtime key value and the value extracted from - // :ref:`x-request-id`. If it is - // missing, or ``use_independent_randomness`` is set to true, the filter will - // randomly sample based on the runtime key value alone. - // ``use_independent_randomness`` can be used for logging kill switches within - // complex nested :ref:`AndFilter - // ` and :ref:`OrFilter - // ` blocks that are easier to - // reason about from a probability perspective (i.e., setting to true will - // cause the filter to behave like an independent random variable when - // composed within logical operator filters). + // Controls how sampling decisions are made. + // + // - Default behavior (``false``): + // + // * Uses the :ref:`x-request-id` as a consistent sampling pivot. + // * When :ref:`x-request-id` is present, sampling will be consistent + // across multiple hosts based on both the ``runtime_key`` and + // :ref:`x-request-id`. + // * Useful for tracking related requests across a distributed system. + // + // - When set to ``true`` or :ref:`x-request-id` is missing: + // + // * Sampling decisions are made randomly based only on the ``runtime_key``. + // * Useful in complex filter configurations (like nested + // :ref:`AndFilter`/ + // :ref:`OrFilter` blocks) where independent probability + // calculations are desired. + // * Can be used to implement logging kill switches with predictable probability distributions. + // bool use_independent_randomness = 3; }