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 java.lang.Object
Utility class that provides method forLoadBalancer
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.(package private) static class
OrcaOobUtil.OrcaReportingHelper
AnOrcaOobUtil.OrcaReportingHelper
wraps a delegatedLoadBalancer.Helper
with additional functionality to manage RPCs for out-of-band ORCA reporting for each backend it establishes connection to.(package private) static class
OrcaOobUtil.SubchannelImpl
-
Field Summary
Fields Modifier and Type Field Description (package private) static io.grpc.Attributes.Key<OrcaOobUtil.SubchannelImpl>
ORCA_REPORTING_STATE_KEY
-
Constructor Summary
Constructors Modifier Constructor Description private
OrcaOobUtil()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static io.grpc.LoadBalancer.Helper
newOrcaReportingHelper(io.grpc.LoadBalancer.Helper delegate)
Creates a newLoadBalancer.Helper
with providedOrcaOobUtil.OrcaOobReportListener
installed to receive callback when an out-of-band ORCA report is received.(package private) 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)
static void
setListener(io.grpc.LoadBalancer.Subchannel subchannel, OrcaOobUtil.OrcaOobReportListener listener, OrcaOobUtil.OrcaReportingConfig config)
UpdateOrcaOobUtil.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.
-
-
-
Field Detail
-
ORCA_REPORTING_STATE_KEY
static final io.grpc.Attributes.Key<OrcaOobUtil.SubchannelImpl> ORCA_REPORTING_STATE_KEY
-
-
Method Detail
-
newOrcaReportingHelper
public static io.grpc.LoadBalancer.Helper newOrcaReportingHelper(io.grpc.LoadBalancer.Helper delegate)
Creates a newLoadBalancer.Helper
with providedOrcaOobUtil.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.
- Leaf policy (e.g., WRR policy)
-
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)
UpdateOrcaOobUtil.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.
-
-