Class OrcaOobUtil

  • @ExperimentalApi("")
    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).
    • 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 void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
                     // listener implements the logic for WRR's usage of backend metrics.
                     OrcaReportingHelper orcaHelper =
                     Subchannel subchannel =
                        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;
        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.

        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.