Package io.grpc.xds.orca

Class OrcaPerRequestUtil

java.lang.Object

io.grpc.xds.orca.OrcaPerRequestUtil

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/9128")
public abstract class OrcaPerRequestUtil
extends Object

Utility class that provides method for LoadBalancer to install listeners to receive per-request backend cost metrics in the format of Open Request Cost Aggregation (ORCA).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	OrcaPerRequestUtil.OrcaPerRequestReportListener	The listener interface for receiving per-request ORCA reports from backends.

Constructor Summary

Constructors

Constructor	Description
OrcaPerRequestUtil()

Method Summary

Modifier and Type	Method	Description
static OrcaPerRequestUtil	getInstance()	Gets an OrcaPerRequestUtil instance that provides actual implementation of newOrcaClientStreamTracerFactory(io.grpc.xds.orca.OrcaPerRequestUtil.OrcaPerRequestReportListener).
abstract ClientStreamTracer.Factory	newOrcaClientStreamTracerFactory(ClientStreamTracer.Factory delegate, OrcaPerRequestUtil.OrcaPerRequestReportListener listener)	Creates a new ClientStreamTracer.Factory with provided OrcaPerRequestUtil.OrcaPerRequestReportListener installed to receive callback when a per-request ORCA report is received.
abstract ClientStreamTracer.Factory	newOrcaClientStreamTracerFactory(OrcaPerRequestUtil.OrcaPerRequestReportListener listener)	Creates a new ClientStreamTracer.Factory with provided OrcaPerRequestUtil.OrcaPerRequestReportListener installed to receive callback when a per-request ORCA report is received.

Methods inherited from class java.lang.Object

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

Constructor Detail

OrcaPerRequestUtil

public OrcaPerRequestUtil()

Method Detail

getInstance

public static OrcaPerRequestUtil getInstance()

Gets an OrcaPerRequestUtil instance that provides actual implementation of newOrcaClientStreamTracerFactory(io.grpc.xds.orca.OrcaPerRequestUtil.OrcaPerRequestReportListener).

newOrcaClientStreamTracerFactory

public abstract ClientStreamTracer.Factory newOrcaClientStreamTracerFactory(OrcaPerRequestUtil.OrcaPerRequestReportListener listener)

Creates a new ClientStreamTracer.Factory with provided OrcaPerRequestUtil.OrcaPerRequestReportListener installed to receive callback when a per-request ORCA report is received.

Example usages for leaf level policy (e.g., WRR policy)

   
   class WrrPicker extends SubchannelPicker {

     public PickResult pickSubchannel(PickSubchannelArgs args) {
       Subchannel subchannel = ...  // WRR picking logic
       return PickResult.withSubchannel(
           subchannel,
           OrcaPerRequestReportUtil.getInstance().newOrcaClientStreamTracerFactory(listener));
     }
   }
   
 

Parameters:

listener - contains the callback to be invoked when a per-request ORCA report is received.

newOrcaClientStreamTracerFactory

public abstract ClientStreamTracer.Factory newOrcaClientStreamTracerFactory(ClientStreamTracer.Factory delegate,
                                                                            OrcaPerRequestUtil.OrcaPerRequestReportListener listener)

Creates a new ClientStreamTracer.Factory with provided OrcaPerRequestUtil.OrcaPerRequestReportListener installed to receive callback when a per-request ORCA report is received.

Example usages:

• Delegating policy (e.g., xDS)

         
         class XdsPicker extends SubchannelPicker {
  
           public PickResult pickSubchannel(PickSubchannelArgs args) {
             SubchannelPicker perLocalityPicker = ...  // locality picking logic
             Result result = perLocalityPicker.pickSubchannel(args);
             return PickResult.withSubchannel(
                 result.getSubchannel(),
                 OrcaPerRequestReportUtil.getInstance().newOrcaClientTracerFactory(
                     result.getStreamTracerFactory(), listener));
  
           }
         }
         
       

• Delegating policy with additional tracing logic

         
         class WrappingPicker extends SubchannelPicker {
  
           public PickResult pickSubchannel(PickSubchannelArgs args) {
             Result result = delegate.pickSubchannel(args);
             return PickResult.withSubchannel(
                 result.getSubchannel(),
                 new ClientStreamTracer.Factory() {
                   public ClientStreamTracer newClientStreamTracer(
                       StreamInfo info, Metadata metadata) {
                     ClientStreamTracer.Factory orcaTracerFactory =
                         OrcaPerRequestReportUtil.getInstance().newOrcaClientStreamTracerFactory(
                             result.getStreamTracerFactory(), listener);
  
                     // Wrap the tracer from the delegate factory if you need to trace the
                     // stream for your own.
                     final ClientStreamTracer orcaTracer =
                         orcaTracerFactory.newClientStreamTracer(info, metadata);
  
                     return ForwardingClientStreamTracer() {
                       protected ClientStreamTracer delegate() {
                         return orcaTracer;
                       }
  
                       public void inboundMessage(int seqNo) {
                         // Handle this event.
                         ...
                       }
                     };
                   }
                 });
           }
         }
         
       

Parameters:

delegate - the delegate factory to produce other client stream tracing.

listener - contains the callback to be invoked when a per-request ORCA report is received.