# ORCA Load Reporting

ORCA is a protocol for reporting load between servers and clients.  This
example shows how to implement this from both the client and server side.  For
more details, please see [gRFC
A51](https://github.com/grpc/proposal/blob/master/A51-custom-backend-metrics.md)

## Try it

```
go run server/main.go
```

```
go run client/main.go
```

## Explanation

gRPC ORCA support provides two different ways to report load data to clients
from servers: out-of-band and per-RPC.  Out-of-band metrics are reported
regularly at some interval on a stream, while per-RPC metrics are reported
along with the trailers at the end of a call.  Both of these mechanisms are
optional and work independently.

The full ORCA API documentation is available here:
https://pkg.go.dev/google.golang.org/grpc/orca

### Out-of-band Metrics

The server registers an ORCA service that is used for out-of-band metrics.  It
does this by using `orca.Register()` and then setting metrics on the returned
`orca.Service` using its methods.

The client receives out-of-band metrics via the LB policy.  It receives
callbacks to a listener by registering the listener on a `SubConn` via
`orca.RegisterOOBListener`.

### Per-RPC Metrics

The server is set up to report query cost metrics in its RPC handler.  For
per-RPC metrics to be reported, the gRPC server must be created with the
`orca.CallMetricsServerOption()` option, and metrics are set by calling methods
on the returned `orca.CallMetricRecorder` from
`orca.CallMetricRecorderFromContext()`.

The client performs one RPC per second.  Per-RPC metrics are available for each
call via the `Done()` callback returned from the LB policy's picker.