orca

Documentation

Overview

Package orca implements Open Request Cost Aggregation, which is an open standard for request cost aggregation and reporting by backends and the corresponding aggregation of such reports by L7 load balancers (such as Envoy) on the data plane. In a proxyless world with gRPC enabled applications, aggregation of such reports will be done by the gRPC client.

Experimental

Notice: All APIs is this package are EXPERIMENTAL and may be changed or removed in a later release.

Index

• Variables
• func CallMetricsServerOption() grpc.ServerOption
• func RegisterOOBListener(sc balancer.SubConn, l OOBListener, opts OOBListenerOptions) (stop func())
• func ToLoadReport(md metadata.MD) (*v3orcapb.OrcaLoadReport, error)
• type CallMetricRecorder
  • func CallMetricRecorderFromContext(ctx context.Context) *CallMetricRecorder
  • func (c *CallMetricRecorder) SetCPUUtilization(val float64)
  • func (c *CallMetricRecorder) SetMemoryUtilization(val float64)
  • func (c *CallMetricRecorder) SetRequestCost(name string, val float64)
  • func (c *CallMetricRecorder) SetUtilization(name string, val float64)
• type OOBListener
• type OOBListenerOptions
• type Service
  • func NewService(opts ServiceOptions) (*Service, error)
  • func Register(s *grpc.Server, opts ServiceOptions) (*Service, error)
  • func (s *Service) DeleteUtilization(name string)
  • func (s *Service) SetCPUUtilization(val float64)
  • func (s *Service) SetMemoryUtilization(val float64)
  • func (s *Service) SetUtilization(name string, val float64)
  • func (s *Service) StreamCoreMetrics(req *v3orcaservicepb.OrcaLoadReportRequest, ...) error
• type ServiceOptions

Variables

var ErrLoadReportMissing = errors.New("orca load report missing in provided metadata")

ErrLoadReportMissing indicates no ORCA load report was found in trailers.

Functions

func CallMetricsServerOption

func CallMetricsServerOption() grpc.ServerOption

CallMetricsServerOption returns a server option which enables the reporting of per-RPC custom backend metrics for unary and streaming RPCs.

Server applications interested in injecting custom backend metrics should pass the server option returned from this function as the first argument to grpc.NewServer().

Subsequently, server RPC handlers can retrieve a reference to the RPC specific custom metrics recorder CallMetricRecorder to be used, via a call to CallMetricRecorderFromContext(), and inject custom metrics at any time during the RPC lifecycle.

The injected custom metrics will be sent as part of trailer metadata, as a binary-encoded ORCA LoadReport protobuf message, with the metadata key being set be "endpoint-load-metrics-bin".

func RegisterOOBListener

func RegisterOOBListener(sc balancer.SubConn, l OOBListener, opts OOBListenerOptions) (stop func())

RegisterOOBListener registers an out-of-band load report listener on sc. Any OOBListener may only be registered once per subchannel at a time. The returned stop function must be called when no longer needed. Do not register a single OOBListener more than once per SubConn.

func ToLoadReport

func ToLoadReport(md metadata.MD) (*v3orcapb.OrcaLoadReport, error)

ToLoadReport unmarshals a binary encoded [ORCA LoadReport] protobuf message from md and returns the corresponding struct. The load report is expected to be stored as the value for key "endpoint-load-metrics-bin".

If no load report was found in the provided metadata, ErrLoadReportMissing is returned.

[ORCA LoadReport]: (https://github.com/cncf/xds/blob/main/xds/data/orca/v3/orca_load_report.proto#L15)

Types

type CallMetricRecorder

type CallMetricRecorder struct {
	// contains filtered or unexported fields
}

CallMetricRecorder provides functionality to record per-RPC custom backend metrics. See CallMetricsServerOption() for more details.

Safe for concurrent use.

func CallMetricRecorderFromContext

func CallMetricRecorderFromContext(ctx context.Context) *CallMetricRecorder

CallMetricRecorderFromContext returns the RPC specific custom metrics recorder CallMetricRecorder embedded in the provided RPC context.

Returns nil if no custom metrics recorder is found in the provided context, which will be the case when custom metrics reporting is not enabled.

func (*CallMetricRecorder) SetCPUUtilization

func (c *CallMetricRecorder) SetCPUUtilization(val float64)

SetCPUUtilization records a measurement for the CPU utilization metric.

func (*CallMetricRecorder) SetMemoryUtilization

func (c *CallMetricRecorder) SetMemoryUtilization(val float64)

SetMemoryUtilization records a measurement for the memory utilization metric.

func (*CallMetricRecorder) SetRequestCost

func (c *CallMetricRecorder) SetRequestCost(name string, val float64)

SetRequestCost records a measurement for a request cost metric, uniquely identifiable by name.

func (*CallMetricRecorder) SetUtilization

func (c *CallMetricRecorder) SetUtilization(name string, val float64)

SetUtilization records a measurement for a utilization metric uniquely identifiable by name.

type OOBListener

type OOBListener interface {
	// OnLoadReport is called when a load report is received.
	OnLoadReport(*v3orcapb.OrcaLoadReport)
}

OOBListener is used to receive out-of-band load reports as they arrive.

type OOBListenerOptions

type OOBListenerOptions struct {
	// ReportInterval specifies how often to request the server to provide a
	// load report.  May be provided less frequently if the server requires a
	// longer interval, or may be provided more frequently if another
	// subscriber requests a shorter interval.
	ReportInterval time.Duration
}

OOBListenerOptions contains options to control how an OOBListener is called.

type Service

type Service struct {
	v3orcaservicegrpc.UnimplementedOpenRcaServiceServer
	// contains filtered or unexported fields
}

Service provides an implementation of the OpenRcaService as defined in the ORCA service protos. Instances of this type must be created via calls to Register() or NewService().

Server applications can use the SetXxx() and DeleteXxx() methods to record measurements corresponding to backend metrics, which eventually get pushed to clients who have initiated the SteamCoreMetrics streaming RPC.

func NewService

func NewService(opts ServiceOptions) (*Service, error)

NewService creates a new ORCA service implementation configured using the provided options.

func Register

func Register(s *grpc.Server, opts ServiceOptions) (*Service, error)

Register creates a new ORCA service implementation configured using the provided options and registers the same on the provided service registrar.

func (*Service) DeleteUtilization

func (s *Service) DeleteUtilization(name string)

DeleteUtilization deletes any previously recorded measurement for a utilization metric uniquely identifiable by name.

func (*Service) SetCPUUtilization

func (s *Service) SetCPUUtilization(val float64)

SetCPUUtilization records a measurement for the CPU utilization metric.

func (*Service) SetMemoryUtilization

func (s *Service) SetMemoryUtilization(val float64)

SetMemoryUtilization records a measurement for the memory utilization metric.

func (*Service) SetUtilization

func (s *Service) SetUtilization(name string, val float64)

SetUtilization records a measurement for a utilization metric uniquely identifiable by name.

func (*Service) StreamCoreMetrics

func (s *Service) StreamCoreMetrics(req *v3orcaservicepb.OrcaLoadReportRequest, stream v3orcaservicegrpc.OpenRcaService_StreamCoreMetricsServer) error

StreamCoreMetrics streams custom backend metrics injected by the server application.

type ServiceOptions

type ServiceOptions struct {
	// MinReportingInterval sets the lower bound for how often out-of-band
	// metrics are reported on the streaming RPC initiated by the client. If
	// unspecified, negative or less than the default value of 30s, the default
	// is used. Clients may request a higher value as part of the
	// StreamCoreMetrics streaming RPC.
	MinReportingInterval time.Duration
	// contains filtered or unexported fields
}

ServiceOptions contains options to configure the ORCA service implementation.