stats/opencensus: OpenCensus instrumentation api

[zasweq]

This PR shows the API for OpenCensus instrumentation in grpc-go. On the client side, an interceptor and stats handler will be part of the dial option, and on the server side, only a stats handler will be registered. The data passed in is the Sampler, to give users a knob on the trace sampling rate, and also a bool to disable traces selectively, needed for observability GA.

RELEASE NOTES: N/A

[dfawley]

Nit: please organize your imports; something like:

import (
	"std"
	"lib"
	"imports"

	"other"
	"imports"

	renamed "imports"
)

[zasweq]

I always see a space between std lib imports and others. However, I sometimes see non grpc imports separated from grpc imports, and renamed imports never separate, only thing I've seen after gRPC imports are something like proto imports. I put spaces in between std lib, other, and grpc.

[dfawley]

Yeah, there are no hard-set rules everyone follows, and without a linter for it, we'll never enforce any particular rule in our repo. It's definitely a widely used convention to separate stdlib imports from others, so as long as we do that I'm fine with whatever other preferences people have.

[zasweq]

Yeah that seems like the most important/always followed distinction.

[dfawley]

Nit: Applications->applications

[zasweq]

Whoops, switched.

[dfawley]

Nit: "Client-side" or "Client side"

[zasweq]

Chose latter. Changed Server Side later in file as well.

[dfawley]

Server-side / Server side

[zasweq]

Switched to latter.

[dfawley]

"... so a registered Stats Handler is the only option that is returned"?

Also it is probably important to call out that (at least for now) it's not possible to use this in conjunction with another stats handler dial/server option.

[zasweq]

Fair enough, will add, but this was never possible right? I added binary logger option in this PR: #5675, which added a second possible binary logger on top of the global at each binary log recording point. Also not visible to external users, but fair point to document.

[dfawley]

Correct, it was never possible. But this is the first time we've ever provided a function that returns a grpc.WithStatsHandler DialOption (/ ServerOption), as opposed to the OC package which provides a grpc/stats.Handler, so it's important to mention that this sets a stats.Handler and no other one should be used on the same client/server (for now). It seems like we will need to support multiple in the not-too-distant future for migration to OpenTelemetry, though.