api: fix description for ORCA utilization precedence and document weight derivation

api/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto

@@ -26,13 +26,20 @@ 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
+// <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.rps_fractional>` (used as
+// 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
+// <envoy_v3_api_field_extensions.load_balancing_policies.client_side_weighted_round_robin.v3.ClientSideWeightedRoundRobin.metric_names_for_computing_utilization>`)
+// 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
 // cluster to the downstream client. This means that if the downstream client is also
@@ -79,10 +86,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 <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.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 ``<map_field_name>.<map_key>``. For example, the string ``named_metrics.foo`` will mean to look for the key ``foo`` in the ORCA :ref:`named_metrics <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.named_metrics>` field.
-  // If none of the specified metrics are present in the load report, then :ref:`cpu_utilization <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.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 <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.application_utilization>` is used if greater than 0, with :ref:`cpu_utilization <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.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.

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 <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.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 ``<map_field_name>.<map_key>``. 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
+  // ``<map_field_name>.<map_key>``. For example, the string
   // ``named_metrics.foo`` will mean to look for the key ``foo`` in the ORCA
   // :ref:`named_metrics <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.named_metrics>`
-  // field. If none of the specified metrics are present in the load report,
-  // then :ref:`cpu_utilization <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.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 <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.application_utilization>`
+  // is used if greater than 0, with
+  // :ref:`cpu_utilization <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.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

docs/root/intro/arch_overview/upstream/load_balancing/load_aware_locality.rst

@@ -132,14 +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. ``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.
+2. ``application_utilization``.
 3. ``cpu_utilization`` -- final fallback.
 
 .. _load_aware_locality_weight_computation:
@@ -317,10 +317,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 ``<map_field_name>.<map_key>`` (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 ``<map_field_name>.<map_key>``
+       (e.g. ``named_metrics.foo``). See
        :ref:`Weight computation <load_aware_locality_weight_computation>` for
        precedence.
    * - ``utilization_variance_threshold``

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 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.
+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 weight of the endpoints that currently have a
+valid weight (or 1 if none are valid).
+
 This policy supports:
 
 - :ref:`Slow start <arch_overview_load_balancing_slow_start>` via