Skip to content

Commit 23bd4ed

Browse files
pellaredpellared
authored
otelgrpc: Deprecate interceptors in favor of stats handlers (#4534)
* otelgrpc: Deprecate interceptors in favor of stats handlers * Update opencensus example
1 parent a3b16ae commit 23bd4ed

File tree

8 files changed

+34
-40
lines changed

8 files changed

+34
-40
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
2828
### Deprecated
2929

3030
- In `go.opentelemetry.io/contrib/exporters/autoexport`, `Option` was renamed to `SpanOption`. The old name is deprecated but continues to be supported as an alias. (#4229)
31+
- The interceptors (`UnaryClientInterceptor`, `StreamClientInterceptor`, `UnaryServerInterceptor`, `StreamServerInterceptor`, `WithInterceptorFilter`) are deprecated. Use stats handlers (`NewClientHandler`, `NewServerHandler`) instead. (#4534)
3132

3233
### Fixed
3334

‎instrumentation/google.golang.org/grpc/otelgrpc/config.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,8 @@ func (o tracerProviderOption) apply(c *config) {
145145
}
146146

147147
// WithInterceptorFilter returns an Option to use the request filter.
148+
//
149+
// Deprecated: Use stats handlers instead.
148150
func WithInterceptorFilter(f Filter) Option {
149151
return interceptorFilterOption{f: f}
150152
}

‎instrumentation/google.golang.org/grpc/otelgrpc/doc.go

Lines changed: 3 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -13,33 +13,10 @@
1313
// limitations under the License.
1414

1515
/*
16-
Package otelgrpc is the instrumentation library for [google.golang.org/grpc]
16+
Package otelgrpc is the instrumentation library for [google.golang.org/grpc].
1717
18-
For now you can instrument your program which use [google.golang.org/grpc] in two ways:
18+
Use [NewClientHandler] with [grpc.WithStatsHandler] to instrument a gRPC client.
1919
20-
- by [grpc.UnaryClientInterceptor], [grpc.UnaryServerInterceptor], [grpc.StreamClientInterceptor], [grpc.StreamServerInterceptor]
21-
- by [stats.Handler]
22-
23-
Notice: Do not use both interceptors and [stats.Handler] at the same time! If so, you will get duplicated spans and the parent/child relationships between spans will also be broken.
24-
25-
We strongly still recommand you to use [stats.Handler], mainly for two reasons:
26-
27-
Functional advantages: [stats.Handler] has more information for user to build more flexible and granular metric, for example
28-
29-
- multiple different types of represent "data length": In [stats.InPayload], there exists "Length", "CompressedLength", "WireLength" to denote the size of uncompressed, compressed payload data, with or without framing data. But in interceptors, we can only got uncompressed data, and this feature is also removed due to performance problem.
30-
31-
- more accurate timestamp: [stats.InPayload]'s "RecvTime" and [stats.OutPayload]'s "SentTime" records more accurate timestamp that server got and sent the message, the timestamp recorded by interceptors depends on the location of this interceptors in the total interceptor chain.
32-
33-
- some other use cases: for example, catch failure of decoding message.
34-
35-
Performance advantages: If too many interceptors are registered in a service, the interceptor chain can become too long, which increases the latency and processing time of the entire RPC call.
36-
37-
[stats.Handler]: https://pkg.go.dev/google.golang.org/grpc/stats#Handler
38-
[grpc.UnaryClientInterceptor]: https://pkg.go.dev/google.golang.org/grpc#UnaryClientInterceptor
39-
[grpc.UnaryServerInterceptor]: https://pkg.go.dev/google.golang.org/grpc#UnaryServerInterceptor
40-
[grpc.StreamClientInterceptor]: https://pkg.go.dev/google.golang.org/grpc#StreamClientInterceptor
41-
[grpc.StreamServerInterceptor]: https://pkg.go.dev/google.golang.org/grpc#StreamServerInterceptor
42-
[stats.OutPayload]: https://pkg.go.dev/google.golang.org/grpc/stats#OutPayload
43-
[stats.InPayload]: https://pkg.go.dev/google.golang.org/grpc/stats#InPayload
20+
Use [NewServerHandler] with [grpc.StatsHandler] to instrument a gRPC server.
4421
*/
4522
package otelgrpc // import "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"

‎instrumentation/google.golang.org/grpc/otelgrpc/example_interceptor_test.go renamed to ‎instrumentation/google.golang.org/grpc/otelgrpc/example_test.go

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -20,18 +20,10 @@ import (
2020
"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
2121
)
2222

23-
func ExampleStreamClientInterceptor() {
24-
_, _ = grpc.Dial("localhost", grpc.WithStreamInterceptor(otelgrpc.StreamClientInterceptor()))
23+
func ExampleNewClientHandler() {
24+
_, _ = grpc.Dial("localhost", grpc.WithStatsHandler(otelgrpc.NewClientHandler()))
2525
}
2626

27-
func ExampleUnaryClientInterceptor() {
28-
_, _ = grpc.Dial("localhost", grpc.WithUnaryInterceptor(otelgrpc.UnaryClientInterceptor()))
29-
}
30-
31-
func ExampleStreamServerInterceptor() {
32-
_ = grpc.NewServer(grpc.StreamInterceptor(otelgrpc.StreamServerInterceptor()))
33-
}
34-
35-
func ExampleUnaryServerInterceptor() {
36-
_ = grpc.NewServer(grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor()))
27+
func ExampleNewServerHandler() {
28+
_ = grpc.NewServer(grpc.StatsHandler(otelgrpc.NewServerHandler()))
3729
}

‎instrumentation/google.golang.org/grpc/otelgrpc/interceptor.go

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,8 @@ var (
6060

6161
// UnaryClientInterceptor returns a grpc.UnaryClientInterceptor suitable
6262
// for use in a grpc.Dial call.
63+
//
64+
// Deprecated: Use [NewClientHandler] instead.
6365
func UnaryClientInterceptor(opts ...Option) grpc.UnaryClientInterceptor {
6466
cfg := newConfig(opts, "client")
6567
tracer := cfg.TracerProvider.Tracer(
@@ -254,6 +256,8 @@ func (w *clientStream) sendStreamEvent(eventType streamEventType, err error) {
254256

255257
// StreamClientInterceptor returns a grpc.StreamClientInterceptor suitable
256258
// for use in a grpc.Dial call.
259+
//
260+
// Deprecated: Use [NewClientHandler] instead.
257261
func StreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor {
258262
cfg := newConfig(opts, "client")
259263
tracer := cfg.TracerProvider.Tracer(
@@ -324,6 +328,8 @@ func StreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor {
324328

325329
// UnaryServerInterceptor returns a grpc.UnaryServerInterceptor suitable
326330
// for use in a grpc.NewServer call.
331+
//
332+
// Deprecated: Use [NewServerHandler] instead.
327333
func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor {
328334
cfg := newConfig(opts, "server")
329335
tracer := cfg.TracerProvider.Tracer(
@@ -445,6 +451,8 @@ func wrapServerStream(ctx context.Context, ss grpc.ServerStream, cfg *config) *s
445451

446452
// StreamServerInterceptor returns a grpc.StreamServerInterceptor suitable
447453
// for use in a grpc.NewServer call.
454+
//
455+
// Deprecated: Use [NewServerHandler] instead.
448456
func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor {
449457
cfg := newConfig(opts, "server")
450458
tracer := cfg.TracerProvider.Tracer(

‎instrumentation/google.golang.org/grpc/otelgrpc/test/grpc_test.go

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,21 +109,25 @@ func TestInterceptors(t *testing.T) {
109109
listener, err := net.Listen("tcp", "127.0.0.1:0")
110110
require.NoError(t, err, "failed to open port")
111111
err = newGrpcTest(listener, []grpc.DialOption{
112+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
112113
grpc.WithUnaryInterceptor(otelgrpc.UnaryClientInterceptor(
113114
otelgrpc.WithTracerProvider(clientUnaryTP),
114115
otelgrpc.WithMessageEvents(otelgrpc.ReceivedEvents, otelgrpc.SentEvents),
115116
)),
117+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
116118
grpc.WithStreamInterceptor(otelgrpc.StreamClientInterceptor(
117119
otelgrpc.WithTracerProvider(clientStreamTP),
118120
otelgrpc.WithMessageEvents(otelgrpc.ReceivedEvents, otelgrpc.SentEvents),
119121
)),
120122
},
121123
[]grpc.ServerOption{
124+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
122125
grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor(
123126
otelgrpc.WithTracerProvider(serverUnaryTP),
124127
otelgrpc.WithMeterProvider(serverUnaryMP),
125128
otelgrpc.WithMessageEvents(otelgrpc.ReceivedEvents, otelgrpc.SentEvents),
126129
)),
130+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
127131
grpc.StreamInterceptor(otelgrpc.StreamServerInterceptor(
128132
otelgrpc.WithTracerProvider(serverStreamTP),
129133
otelgrpc.WithMessageEvents(otelgrpc.ReceivedEvents, otelgrpc.SentEvents),

‎instrumentation/google.golang.org/grpc/otelgrpc/test/interceptor_test.go

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,19 +92,23 @@ func TestUnaryClientInterceptor(t *testing.T) {
9292

9393
sr := tracetest.NewSpanRecorder()
9494
tp := trace.NewTracerProvider(trace.WithSpanProcessor(sr))
95+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
9596
unaryInterceptor := otelgrpc.UnaryClientInterceptor(
9697
otelgrpc.WithTracerProvider(tp),
9798
otelgrpc.WithMessageEvents(otelgrpc.ReceivedEvents, otelgrpc.SentEvents),
9899
otelgrpc.WithSpanOptions(oteltrace.WithAttributes(attribute.Bool("custom", true))),
99100
)
101+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
100102
unaryInterceptorOnlySentEvents := otelgrpc.UnaryClientInterceptor(
101103
otelgrpc.WithTracerProvider(tp),
102104
otelgrpc.WithMessageEvents(otelgrpc.SentEvents),
103105
)
106+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
104107
unaryInterceptorOnlyReceivedEvents := otelgrpc.UnaryClientInterceptor(
105108
otelgrpc.WithTracerProvider(tp),
106109
otelgrpc.WithMessageEvents(otelgrpc.ReceivedEvents),
107110
)
111+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
108112
unaryInterceptorNoEvents := otelgrpc.UnaryClientInterceptor(
109113
otelgrpc.WithTracerProvider(tp),
110114
)
@@ -405,6 +409,7 @@ func createInterceptedStreamClient(t *testing.T, method string, opts clientStrea
405409
if len(opts.Events) > 0 {
406410
interceptorOpts = append(interceptorOpts, otelgrpc.WithMessageEvents(opts.Events...))
407411
}
412+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
408413
streamCI := otelgrpc.StreamClientInterceptor(interceptorOpts...)
409414

410415
streamClient, err := streamCI(
@@ -651,6 +656,7 @@ func TestStreamClientInterceptorCancelContext(t *testing.T) {
651656
// tracer
652657
sr := tracetest.NewSpanRecorder()
653658
tp := trace.NewTracerProvider(trace.WithSpanProcessor(sr))
659+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
654660
streamCI := otelgrpc.StreamClientInterceptor(
655661
otelgrpc.WithTracerProvider(tp),
656662
otelgrpc.WithMessageEvents(otelgrpc.ReceivedEvents, otelgrpc.SentEvents),
@@ -714,6 +720,7 @@ func TestStreamClientInterceptorWithError(t *testing.T) {
714720
// tracer
715721
sr := tracetest.NewSpanRecorder()
716722
tp := trace.NewTracerProvider(trace.WithSpanProcessor(sr))
723+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
717724
streamCI := otelgrpc.StreamClientInterceptor(
718725
otelgrpc.WithTracerProvider(tp),
719726
otelgrpc.WithMessageEvents(otelgrpc.ReceivedEvents, otelgrpc.SentEvents),
@@ -877,6 +884,7 @@ func TestUnaryServerInterceptor(t *testing.T) {
877884
mr := metric.NewManualReader()
878885
mp := metric.NewMeterProvider(metric.WithReader(mr))
879886

887+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
880888
usi := otelgrpc.UnaryServerInterceptor(
881889
otelgrpc.WithTracerProvider(tp),
882890
otelgrpc.WithMeterProvider(mp),
@@ -937,6 +945,7 @@ func TestUnaryServerInterceptorEvents(t *testing.T) {
937945
if len(testCase.Events) > 0 {
938946
opts = append(opts, otelgrpc.WithMessageEvents(testCase.Events...))
939947
}
948+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
940949
usi := otelgrpc.UnaryServerInterceptor(opts...)
941950
grpcCode := grpc_codes.OK
942951
name := grpcCode.String()
@@ -998,6 +1007,7 @@ func TestStreamServerInterceptor(t *testing.T) {
9981007
sr := tracetest.NewSpanRecorder()
9991008
tp := trace.NewTracerProvider(trace.WithSpanProcessor(sr))
10001009

1010+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
10011011
usi := otelgrpc.StreamServerInterceptor(
10021012
otelgrpc.WithTracerProvider(tp),
10031013
)
@@ -1039,6 +1049,7 @@ func TestStreamServerInterceptorEvents(t *testing.T) {
10391049
if len(testCase.Events) > 0 {
10401050
opts = append(opts, otelgrpc.WithMessageEvents(testCase.Events...))
10411051
}
1052+
//nolint:staticcheck // Interceptors are deprecated and will be removed in the next release.
10421053
usi := otelgrpc.StreamServerInterceptor(opts...)
10431054
stream := &mockServerStream{}
10441055

‎propagators/opencensus/examples/opentelemetry_server/server.go

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,7 @@ func main() {
7171
// handler to enable tracing.
7272
log.Println("Starting the GRPC server, and using the OpenCensus binary propagation format.")
7373
s := grpc.NewServer(
74-
grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor(otelgrpc.WithPropagators(opencensus.Binary{}))),
75-
grpc.StreamInterceptor(otelgrpc.StreamServerInterceptor(otelgrpc.WithPropagators(opencensus.Binary{}))))
74+
grpc.StatsHandler(otelgrpc.NewServerHandler(otelgrpc.WithPropagators(opencensus.Binary{}))))
7675
pb.RegisterGreeterServer(s, &server{})
7776

7877
if err := s.Serve(lis); err != nil {

0 commit comments

Comments
 (0)