Class OrcaOobUtil

java.lang.Object
io.grpc.xds.orca.OrcaOobUtil

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/9129") public final class OrcaOobUtil extends Object
Utility class that provides method for LoadBalancer to install listeners to receive out-of-band backend metrics in the format of Open Request Cost Aggregation (ORCA).
  • Field Details

  • Constructor Details

    • OrcaOobUtil

      private OrcaOobUtil()
  • Method Details

    • newOrcaReportingHelper

      public static io.grpc.LoadBalancer.Helper newOrcaReportingHelper(io.grpc.LoadBalancer.Helper delegate)
      Creates a new LoadBalancer.Helper with provided OrcaOobUtil.OrcaOobReportListener installed to receive callback when an out-of-band ORCA report is received.

      Example usages:

      • Leaf policy (e.g., WRR policy)
               
               class WrrLoadbalancer extends LoadBalancer {
                 private final Helper originHelper;  // the original Helper
        
                 public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
                   // listener implements the logic for WRR's usage of backend metrics.
                   OrcaReportingHelper orcaHelper =
                       OrcaOobUtil.newOrcaReportingHelper(originHelper);
                   Subchannel subchannel =
                       orcaHelper.createSubchannel(CreateSubchannelArgs.newBuilder()...);
                   OrcaOobUtil.setListener(
                      subchannel,
                      listener,
                      OrcaRerportingConfig.newBuilder().setReportInterval(30, SECOND).build());
                   ...
                 }
               }
               
             
      • Delegating policy doing per-child-policy aggregation
               
               class XdsLoadBalancer extends LoadBalancer {
                 private final Helper orcaHelper;  // the original Helper
        
                 public XdsLoadBalancer(LoadBalancer.Helper helper) {
                   this.orcaHelper = OrcaUtil.newOrcaReportingHelper(helper);
                 }
                 private void createChildPolicy(
                     Locality locality, LoadBalancerProvider childPolicyProvider) {
                   // Each Locality has a child policy, and the parent does per-locality aggregation by
                   // summing everything up.
        
                   // Create an OrcaReportingHelperWrapper for each Locality.
                   // listener implements the logic for locality-level backend metric aggregation.
                   LoadBalancer childLb = childPolicyProvider.newLoadBalancer(
                     new ForwardingLoadBalancerHelper() {
                       public Subchannel createSubchannel(CreateSubchannelArgs args) {
                         Subchannel subchannel = super.createSubchannel(args);
                         OrcaOobUtil.setListener(subchannel, listener,
                         OrcaReportingConfig.newBuilder().setReportInterval(30, SECOND).build());
                         return subchannel;
                       }
                       public LoadBalancer.Helper delegate() {
                         return orcaHelper;
                       }
                     });
                 }
               }
               
             
      Parameters:
      delegate - the delegate helper that provides essentials for establishing subchannels to backends.
    • newOrcaReportingHelper

      static io.grpc.LoadBalancer.Helper newOrcaReportingHelper(io.grpc.LoadBalancer.Helper delegate, io.grpc.internal.BackoffPolicy.Provider backoffPolicyProvider, com.google.common.base.Supplier<com.google.common.base.Stopwatch> stopwatchSupplier)
    • setListener

      public static void setListener(io.grpc.LoadBalancer.Subchannel subchannel, OrcaOobUtil.OrcaOobReportListener listener, OrcaOobUtil.OrcaReportingConfig config)
      Update OrcaOobUtil.OrcaOobReportListener to receive Out-of-Band metrics report for the particular subchannel connection, and set the configuration of receiving ORCA reports, such as the interval of receiving reports. Set listener to null to remove listener, and the config will have no effect.

      This method needs to be called from the SynchronizationContext returned by the wrapped helper's LoadBalancer.Helper.getSynchronizationContext().

      Each load balancing policy must call this method to configure the backend load reporting. Otherwise, it will not receive ORCA reports.

      If multiple load balancing policies configure reporting with different intervals, reports come with the minimum of those intervals.

      Parameters:
      subchannel - the server connected by this subchannel to receive the metrics.
      listener - the callback upon receiving backend metrics from the Out-Of-Band stream. Setting to null to removes the listener from the subchannel.
      config - the configuration to be set. It has no effect when listener is null.