Package io.grpc.xds.orca

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).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	OrcaOobUtil.OrcaOobReportListener	The listener interface for receiving out-of-band ORCA reports from backends.
static class	OrcaOobUtil.OrcaReportingConfig	Configuration for out-of-band ORCA reporting service RPC.

Method Summary

Modifier and Type	Method	Description
static LoadBalancer.Helper	newOrcaReportingHelper(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.
static void	setListener(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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newOrcaReportingHelper

public static LoadBalancer.Helper newOrcaReportingHelper(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 Status acceptResolvedAddresses(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.

setListener

public static void setListener(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.