From c100424508a4568b2f64324ffd9fd3a2878b2668 Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Mon, 6 Jul 2026 14:52:55 -0600 Subject: [PATCH 1/4] named-metrics-first ORCA utilization precedence Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- .../v3/client_side_weighted_round_robin.proto | 7 ++++--- .../v3/load_aware_locality.proto | 21 +++++++++++-------- .../load_balancing/load_aware_locality.rst | 15 +++++++------ 3 files changed, 23 insertions(+), 20 deletions(-) diff --git a/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto b/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto index 7c47e6d155548..6c480f989aed2 100644 --- a/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +++ b/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto @@ -79,10 +79,11 @@ message ClientSideWeightedRoundRobin { // Default is 1.0. google.protobuf.FloatValue error_utilization_penalty = 6 [(validate.rules).float = {gte: 0.0}]; - // By default, endpoint weight is computed based on the :ref:`application_utilization ` field reported by the endpoint. - // If that field is not set, then utilization will instead be computed by taking the max of the values of the metrics specified here. + // Specifies the metrics used to compute the endpoint utilization from which weight is derived. // For map fields in the ORCA proto, the string will be of the form ``.``. For example, the string ``named_metrics.foo`` will mean to look for the key ``foo`` in the ORCA :ref:`named_metrics ` field. - // If none of the specified metrics are present in the load report, then :ref:`cpu_utilization ` is used instead. + // Utilization is the max of the values of the metrics specified here, when that max is greater than 0. + // Otherwise :ref:`application_utilization ` is used if greater than 0, with :ref:`cpu_utilization ` as the final fallback. + // Disabling the runtime flag ``envoy.reloadable_features.orca_weight_manager_use_named_metrics_first`` restores the legacy order, preferring ``application_utilization`` over these metrics. repeated string metric_names_for_computing_utilization = 7; // Configuration for slow start mode. diff --git a/api/envoy/extensions/load_balancing_policies/load_aware_locality/v3/load_aware_locality.proto b/api/envoy/extensions/load_balancing_policies/load_aware_locality/v3/load_aware_locality.proto index ec573dc86a1f6..e3df8a1b72f3b 100644 --- a/api/envoy/extensions/load_balancing_policies/load_aware_locality/v3/load_aware_locality.proto +++ b/api/envoy/extensions/load_balancing_policies/load_aware_locality/v3/load_aware_locality.proto @@ -32,17 +32,20 @@ message LoadAwareLocality { google.protobuf.Duration weight_update_period = 2 [(validate.rules).duration = {gte {nanos: 100000000}}]; - // By default, endpoint utilization is computed based on the - // :ref:`application_utilization ` - // field reported by the endpoint. If that field is not set, then utilization - // will instead be computed by taking the max of the values of the metrics - // specified here. For map fields in the ORCA proto, the string will be of - // the form ``.``. For example, the string + // Specifies the metrics used to compute endpoint utilization. For map + // fields in the ORCA proto, the string will be of the form + // ``.``. For example, the string // ``named_metrics.foo`` will mean to look for the key ``foo`` in the ORCA // :ref:`named_metrics ` - // field. If none of the specified metrics are present in the load report, - // then :ref:`cpu_utilization ` - // is used instead. + // field. Utilization is the max of the values of the metrics specified + // here, when that max is greater than 0. Otherwise + // :ref:`application_utilization ` + // is used if greater than 0, with + // :ref:`cpu_utilization ` + // as the final fallback. Disabling the runtime flag + // ``envoy.reloadable_features.orca_weight_manager_use_named_metrics_first`` + // restores the legacy order, preferring ``application_utilization`` over + // these metrics. repeated string metric_names_for_computing_utilization = 3; // When the local locality's utilization is at most this threshold above the diff --git a/docs/root/intro/arch_overview/upstream/load_balancing/load_aware_locality.rst b/docs/root/intro/arch_overview/upstream/load_balancing/load_aware_locality.rst index 055658a40f421..55493d6f2e5d2 100644 --- a/docs/root/intro/arch_overview/upstream/load_balancing/load_aware_locality.rst +++ b/docs/root/intro/arch_overview/upstream/load_balancing/load_aware_locality.rst @@ -136,10 +136,9 @@ extraction as CSWRR (precedence may be flipped by the ``envoy.reloadable_features.orca_weight_manager_use_named_metrics_first`` runtime feature). By default: -1. ``application_utilization`` -- value in [0, 1], used when reported and - greater than 0. -2. Named metrics via ``metric_names_for_computing_utilization`` -- max of - present values, used when ``application_utilization`` is not reported. +1. Named metrics via ``metric_names_for_computing_utilization`` -- max of + present values, used when that max is greater than 0. +2. ``application_utilization`` -- value in [0, 1], used when greater than 0. 3. ``cpu_utilization`` -- final fallback. .. _load_aware_locality_weight_computation: @@ -317,10 +316,10 @@ Configuration parameters least 100 ms. * - ``metric_names_for_computing_utilization`` - (unset) - - Named ORCA metrics used to compute utilization when - ``application_utilization`` is not reported. The max of matching - values is taken. Map entries use ``.`` (e.g. - ``named_metrics.foo``). See + - Named ORCA metrics used to compute utilization. By default the max of + matching values takes precedence over ``application_utilization`` when + that max is greater than 0. Map entries use ``.`` + (e.g. ``named_metrics.foo``). See :ref:`Weight computation ` for precedence. * - ``utilization_variance_threshold`` From a76214126f1190931e2ea74f482fe83b9831ea01 Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:40:20 -0400 Subject: [PATCH 2/4] Clarify rps_fractional requirement and tweaks Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- .../v3/client_side_weighted_round_robin.proto | 20 ++++++++++++------- .../load_balancing/load_aware_locality.rst | 7 ++++--- .../load_balancing/load_balancers.rst | 19 ++++++++++++++++++ 3 files changed, 36 insertions(+), 10 deletions(-) diff --git a/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto b/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto index 6c480f989aed2..262b579057509 100644 --- a/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +++ b/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto @@ -26,13 +26,19 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // the endpoint weights are sent by the control plane via EDS. However, // in this policy, the endpoint weights are instead determined via qps (queries // per second), eps (errors per second), and utilization metrics sent by the -// endpoint using the Open Request Cost Aggregation (ORCA) protocol. Utilization -// is determined by using the ORCA application_utilization field, if set, or -// else falling back to the cpu_utilization field. All queries count toward qps, -// regardless of result. Only failed queries count toward eps. A config -// parameter error_utilization_penalty controls the penalty to adjust endpoint -// weights using eps and qps. The weight of a given endpoint is computed as: -// ``qps / (utilization + eps/qps * error_utilization_penalty)``. +// endpoint using the Open Request Cost Aggregation (ORCA) protocol. All queries +// count toward qps, regardless of result. Only failed queries count toward eps. +// A config parameter error_utilization_penalty controls the penalty to adjust +// endpoint weights using eps and qps. The weight of a given endpoint is computed +// as: ``qps / (utilization + eps/qps * error_utilization_penalty)``. +// +// For a load report to update an endpoint's weight it must set :ref:`rps_fractional +// ` (used as +// qps) greater than 0 and provide a utilization signal greater than 0 (see +// :ref:`metric_names_for_computing_utilization +// `). +// Reports that fail to do so are ignored, and an endpoint with no valid weight is +// assigned the median weight of the endpoints that have one. // // Note that Envoy will forward the ORCA response headers/trailers from the upstream // cluster to the downstream client. This means that if the downstream client is also diff --git a/docs/root/intro/arch_overview/upstream/load_balancing/load_aware_locality.rst b/docs/root/intro/arch_overview/upstream/load_balancing/load_aware_locality.rst index 55493d6f2e5d2..5cb3acb8dadb7 100644 --- a/docs/root/intro/arch_overview/upstream/load_balancing/load_aware_locality.rst +++ b/docs/root/intro/arch_overview/upstream/load_balancing/load_aware_locality.rst @@ -132,13 +132,14 @@ per-endpoint capacity. Each consumer attaches independent ``HostLbPolicyData`` entries, so the two policies do not interfere. Utilization is derived from each host's ORCA report using the same -extraction as CSWRR (precedence may be flipped by the +extraction as CSWRR, which takes the first source whose value is greater +than 0 (precedence may be flipped by the ``envoy.reloadable_features.orca_weight_manager_use_named_metrics_first`` runtime feature). By default: 1. Named metrics via ``metric_names_for_computing_utilization`` -- max of - present values, used when that max is greater than 0. -2. ``application_utilization`` -- value in [0, 1], used when greater than 0. + present values. +2. ``application_utilization``. 3. ``cpu_utilization`` -- final fallback. .. _load_aware_locality_weight_computation: diff --git a/docs/root/intro/arch_overview/upstream/load_balancing/load_balancers.rst b/docs/root/intro/arch_overview/upstream/load_balancing/load_balancers.rst index 59536f8e492ac..8bb5e80a51578 100644 --- a/docs/root/intro/arch_overview/upstream/load_balancing/load_balancers.rst +++ b/docs/root/intro/arch_overview/upstream/load_balancing/load_balancers.rst @@ -35,6 +35,25 @@ Unlike classic round robin, endpoint weights are derived from load reports sent upstreams via ORCA (Open Request Cost Aggregation), incorporating queries-per-second (QPS), errors-per-second (EPS) and utilization to adaptively balance load. +Endpoint weights are recomputed periodically from each endpoint's most recent ORCA +report as ``qps / (utilization + eps/qps * error_utilization_penalty)``, where +``qps`` is the report's ``rps_fractional`` field. Both ``qps`` and the resolved +``utilization`` must be greater than 0; a report that fails either requirement is +ignored. Utilization is resolved in the following order, taking the first source whose +value is greater than 0 (precedence may be flipped by the +``envoy.reloadable_features.orca_weight_manager_use_named_metrics_first`` runtime +feature). By default: + +1. Named metrics via ``metric_names_for_computing_utilization`` -- max of present + values. +2. ``application_utilization``. +3. ``cpu_utilization`` -- final fallback. + +While an endpoint has no valid weight -- because its reports are being ignored, or +during the initial ``blackout_period``, or after ``weight_expiration_period`` has +elapsed -- it is assigned the median of the endpoints that currently have a valid +weight (or 1 if none are valid). + This policy supports: - :ref:`Slow start ` via From 730fbd0e966dd9503c69b2f81db0ad857c58bb50 Mon Sep 17 00:00:00 2001 From: jukie <10012479+jukie@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:51:58 -0400 Subject: [PATCH 3/4] correction Signed-off-by: jukie <10012479+jukie@users.noreply.github.com> --- .../v3/client_side_weighted_round_robin.proto | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto b/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto index 262b579057509..589eb4c935db6 100644 --- a/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +++ b/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto @@ -34,11 +34,11 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // // For a load report to update an endpoint's weight it must set :ref:`rps_fractional // ` (used as -// qps) greater than 0 and provide a utilization signal greater than 0 (see +// qps) greater than 0, and the resolved utilization (see // :ref:`metric_names_for_computing_utilization -// `). -// Reports that fail to do so are ignored, and an endpoint with no valid weight is -// assigned the median weight of the endpoints that have one. +// `) +// must be greater than 0. Reports that fail to do so are ignored, and an endpoint +// with no valid weight is assigned the median weight of the endpoints that have one. // // Note that Envoy will forward the ORCA response headers/trailers from the upstream // cluster to the downstream client. This means that if the downstream client is also From dcc5a1bcd32355c1621f60415544e8bde3b44574 Mon Sep 17 00:00:00 2001 From: Isaac Wilson Date: Wed, 8 Jul 2026 09:32:09 -0700 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Isaac Wilson --- .../v3/client_side_weighted_round_robin.proto | 7 ++++--- .../upstream/load_balancing/load_balancers.rst | 16 ++++++++-------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto b/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto index 589eb4c935db6..dade9fde0e3b1 100644 --- a/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +++ b/api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto @@ -32,12 +32,13 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // endpoint weights using eps and qps. The weight of a given endpoint is computed // as: ``qps / (utilization + eps/qps * error_utilization_penalty)``. // -// For a load report to update an endpoint's weight it must set :ref:`rps_fractional +// For a load report to update an endpoint's weight, it must set :ref:`rps_fractional // ` (used as -// qps) greater than 0, and the resolved utilization (see +// qps) greater than 0, and the final utilization (resolved utilization plus any +// error penalty) must be greater than 0. Resolved utilization (see // :ref:`metric_names_for_computing_utilization // `) -// must be greater than 0. Reports that fail to do so are ignored, and an endpoint +// is used as the baseline. Reports that fail to do so are ignored, and an endpoint // with no valid weight is assigned the median weight of the endpoints that have one. // // Note that Envoy will forward the ORCA response headers/trailers from the upstream diff --git a/docs/root/intro/arch_overview/upstream/load_balancing/load_balancers.rst b/docs/root/intro/arch_overview/upstream/load_balancing/load_balancers.rst index 8bb5e80a51578..97538e34bb776 100644 --- a/docs/root/intro/arch_overview/upstream/load_balancing/load_balancers.rst +++ b/docs/root/intro/arch_overview/upstream/load_balancing/load_balancers.rst @@ -37,12 +37,12 @@ errors-per-second (EPS) and utilization to adaptively balance load. Endpoint weights are recomputed periodically from each endpoint's most recent ORCA report as ``qps / (utilization + eps/qps * error_utilization_penalty)``, where -``qps`` is the report's ``rps_fractional`` field. Both ``qps`` and the resolved -``utilization`` must be greater than 0; a report that fails either requirement is -ignored. Utilization is resolved in the following order, taking the first source whose -value is greater than 0 (precedence may be flipped by the -``envoy.reloadable_features.orca_weight_manager_use_named_metrics_first`` runtime -feature). By default: +``qps`` is the report's ``rps_fractional`` field. Both ``qps`` and the final +``utilization`` (resolved utilization plus any error penalty) must be greater than 0; +a report that fails either requirement is ignored. Utilization is resolved in the +following order, taking the first source whose value is greater than 0 (precedence +may be flipped by the ``envoy.reloadable_features.orca_weight_manager_use_named_metrics_first`` +runtime feature). By default: 1. Named metrics via ``metric_names_for_computing_utilization`` -- max of present values. @@ -51,8 +51,8 @@ feature). By default: While an endpoint has no valid weight -- because its reports are being ignored, or during the initial ``blackout_period``, or after ``weight_expiration_period`` has -elapsed -- it is assigned the median of the endpoints that currently have a valid -weight (or 1 if none are valid). +elapsed -- it is assigned the median weight of the endpoints that currently have a +valid weight (or 1 if none are valid). This policy supports: