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

  • Field Details

    • NOOP_CLIENT_STREAM_TRACER

      private static final io.grpc.ClientStreamTracer NOOP_CLIENT_STREAM_TRACER

    • NOOP_CLIENT_STREAM_TRACER_FACTORY

      private static final io.grpc.ClientStreamTracer.Factory NOOP_CLIENT_STREAM_TRACER_FACTORY

    • DEFAULT_INSTANCE

      private static final OrcaPerRequestUtil DEFAULT_INSTANCE

  • Constructor Details

    • OrcaPerRequestUtil

      public OrcaPerRequestUtil()

  • Method Details

    • getInstance

      public static OrcaPerRequestUtil getInstance()
      Gets an OrcaPerRequestUtil instance that provides actual implementation of newOrcaClientStreamTracerFactory(OrcaPerRequestUtil.OrcaPerRequestReportListener).

    • newOrcaClientStreamTracerFactory

      public abstract io.grpc.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 io.grpc.ClientStreamTracer.Factory newOrcaClientStreamTracerFactory(io.grpc.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.

    • fromOrcaLoadReport

      static io.grpc.services.MetricReport fromOrcaLoadReport(OrcaLoadReport loadReport)