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

[jukie]

Commit Message: api: fix description for ORCA utilization precedence

Additional Description:
The metric_names_for_computing_utilization field comments in client_side_weighted_round_robin/load_aware_locality still describe the legacy utilization-precedence order. After #44196, envoy.reloadable_features.orca_weight_manager_use_named_metrics_first now defaults to true so the described order and gating was incorrect. They now match the runtime-dependent behavior of the shared getUtilizationFromOrcaReport helper:

1. max of the named metrics, used when that max is > 0
2. else application_utilization, used when > 0
3. else cpu_utilization

Also includes clarification about rps_fractional requirement and weight derivation.

Risk Level: Low
Testing: N/A
Docs Changes: Updated load_aware_locality docs
Release Notes: None
Platform Specific Features: N/A
API Considerations: Comment only changes

[repokitteh-read-only]

As a reminder, PRs marked as draft will not be automatically assigned reviewers,
or be handled by maintainer-oncall triage.

Please mark your PR as ready when you want it to be reviewed!

🐱

Caused by: #46002 was opened by jukie.

see: more, trace.

[repokitteh-read-only]

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy/|docs/root/api-docs/).
envoyproxy/api-shepherds assignee is @markdroth
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #46002 was ready_for_review by jukie.

see: more, trace.

[jukie]

CC @efimki for #44196

[jukie]

/gemini review

[gemini-code-assist]

Code Review

This pull request updates the protobuf and RST documentation for client-side weighted round-robin (CSWRR) and load-aware locality load balancing policies to clarify how endpoint utilization is resolved from ORCA reports, including the default precedence of named metrics over application utilization. The review feedback correctly identifies an inaccuracy in the updated documentation: the code actually checks if the final utilization (resolved utilization plus any error penalty) is greater than 0, rather than just the resolved utilization itself. Actionable suggestions were provided to correct this in both the proto comments and the RST documentation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.