From e219e082e6b4e7e8c05014c93162fd95e920ba21 Mon Sep 17 00:00:00 2001 From: Andrey Slotin Date: Thu, 19 Mar 2020 20:34:22 +0100 Subject: [PATCH 1/3] Fix typos in example comments --- instrumentation/instagrpc/README.md | 2 +- instrumentation/instagrpc/example_test.go | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/instrumentation/instagrpc/README.md b/instrumentation/instagrpc/README.md index af2970bc2..fa19bb435 100644 --- a/instrumentation/instagrpc/README.md +++ b/instrumentation/instagrpc/README.md @@ -52,7 +52,7 @@ func (s MyServer) SampleCall(ctx context.Context, req *MyRequest) (*MyResponse, ### Instrumenting a client Similar to the server instrumentation, to instrument a GRPC client add `instagrpc.UnaryClientInterceptor()` and -`instagrpc.StreamClientInterceptor()` into the list of dial options passed to the `grpc.Dial()` call. The interceptor +`instagrpc.StreamClientInterceptor()` to the list of dial options passed to the `grpc.Dial()` call. The interceptor will inject the trace context into each outgoing request made with this connection: ```go diff --git a/instrumentation/instagrpc/example_test.go b/instrumentation/instagrpc/example_test.go index c774cdd40..259fc501b 100644 --- a/instrumentation/instagrpc/example_test.go +++ b/instrumentation/instagrpc/example_test.go @@ -24,8 +24,8 @@ type TestServiceServer struct { // UnaryCall responds with a static greeting from server func (s TestServiceServer) UnaryCall(ctx context.Context, req *grpctest.SimpleRequest) (*grpctest.SimpleResponse, error) { - // Extract the parent span and use its tracer to initialize any child spans to trace the calls - // inside the hander, e.g. database queries, 3rd-aprty API requests, etc. + // Extract the parent span and use its tracer to initialize any child spans to trace the calls + // inside the handler, e.g. database queries, 3rd-party API requests, etc. if parent, ok := instana.SpanFromContext(ctx); ok { sp := parent.Tracer().StartSpan("unary-call") defer sp.Finish() @@ -51,8 +51,8 @@ func setupServer() (net.Addr, error) { return nil, fmt.Errorf("failed to start listener: %s", err) } - // To instrument server calls add instagrpc.UnaryServerInterceptor(tracer) and - // instagrpc.StreamServerInterceptor(tracer) to the list of server options when + // To instrument server calls add instagrpc.UnaryServerInterceptor(sensor) and + // instagrpc.StreamServerInterceptor(sensor) to the list of server options when // initializing the server srv := grpc.NewServer( grpc.UnaryInterceptor(instagrpc.UnaryServerInterceptor(sensor)), @@ -78,8 +78,8 @@ func Example() { // Initialize client tracer sensor := instana.NewSensor("grpc-client") - // To instrument client calls add instagrpc.UnaryClientInterceptor(tracer) and - // instagrpc.StringClientInterceptor(tracer) to the DialOption list while dialing + // To instrument client calls add instagrpc.UnaryClientInterceptor(sensor) and + // instagrpc.StringClientInterceptor(sensor) to the DialOption list while dialing // the GRPC server. conn, err := grpc.Dial( serverAddr.String(), From 826f3767c00e1ae31fd9c0395a2ff12538d5a922 Mon Sep 17 00:00:00 2001 From: Andrey Slotin Date: Thu, 19 Mar 2020 20:40:41 +0100 Subject: [PATCH 2/3] Link method names to their godoc in the instagrpc README --- instrumentation/instagrpc/README.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/instrumentation/instagrpc/README.md b/instrumentation/instagrpc/README.md index fa19bb435..1d6b9f66c 100644 --- a/instrumentation/instagrpc/README.md +++ b/instrumentation/instagrpc/README.md @@ -24,9 +24,10 @@ You can create a new instance of Instana tracer using `instana.NewTracer()`. ### Instrumenting a server -To instrument your GRPC server instance include `instagrpc.UnaryServerInterceptor()` and `instagrpc.StreamServerInterceptor()` -into the list of server options passed to `grpc.NewServer()`. These interceptors will use the provided `instana.Sensor` to -handle the OpenTracing headers, start a new span for each incoming request and inject it into the handler: +To instrument your GRPC server instance include [`instagrpc.UnaryServerInterceptor()`][UnaryServerInterceptor] and +[`instagrpc.StreamServerInterceptor()`][StreamServerInterceptor] into the list of server options passed to `grpc.NewServer()`. +These interceptors will use the provided [`instana.Sensor`][Sensor] to handle the OpenTracing headers, start a new span for each incoming +request and inject it into the handler: ```go // initialize a new tracer instance @@ -40,7 +41,7 @@ srv := grpc.NewServer( ) ``` -The parent span can be than retrieved inside the handler using `instana.ContextFromSpan()`: +The parent span can be than retrieved inside the handler using [`instana.SpanFromContext()`][SpanFromContext]: ```go func (s MyServer) SampleCall(ctx context.Context, req *MyRequest) (*MyResponse, error) { @@ -51,8 +52,8 @@ func (s MyServer) SampleCall(ctx context.Context, req *MyRequest) (*MyResponse, ### Instrumenting a client -Similar to the server instrumentation, to instrument a GRPC client add `instagrpc.UnaryClientInterceptor()` and -`instagrpc.StreamClientInterceptor()` to the list of dial options passed to the `grpc.Dial()` call. The interceptor +Similar to the server instrumentation, to instrument a GRPC client add [`instagrpc.UnaryClientInterceptor()`][UnaryClientInterceptor] and +[`instagrpc.StreamClientInterceptor()`][StreamClientInterceptor] to the list of dial options passed to the `grpc.Dial()` call. The interceptor will inject the trace context into each outgoing request made with this connection: ```go @@ -64,6 +65,13 @@ conn, err := grpc.Dial( ) ``` -If the context contains an active span stored using `instana.ContextWithSpan()`, the tracer of this span will be used instead. +If the context contains an active span stored using [`instana.ContextWithSpan()`][ContextWithSpan], the tracer of this span will be used instead. [godoc]: https://pkg.go.dev/github.com/instana/go-sensor/instrumentation/instagrpc +[StreamClientInterceptor]: https://pkg.go.dev/github.com/instana/go-sensor/instrumentation/instagrpc?tab=doc#StreamClientInterceptor +[StreamServerInterceptor]: https://pkg.go.dev/github.com/instana/go-sensor/instrumentation/instagrpc?tab=doc#StreamServerInterceptor +[UnaryClientInterceptor]: https://pkg.go.dev/github.com/instana/go-sensor/instrumentation/instagrpc?tab=doc#UnaryClientInterceptor +[UnaryServerInterceptor]: https://pkg.go.dev/github.com/instana/go-sensor/instrumentation/instagrpc?tab=doc#UnaryServerInterceptor +[Sensor]: https://pkg.go.dev/github.com/instana/go-sensor/?tab=doc#Sensor +[SpanFromContext]: https://pkg.go.dev/github.com/instana/go-sensor/?tab=doc#SpanFromContext +[ContextWithSpan]: https://pkg.go.dev/github.com/instana/go-sensor/?tab=doc#ContextWithSpan From 67a0e72fa8f8f1ea179763be853c06cc6bd93d02 Mon Sep 17 00:00:00 2001 From: Andrey Slotin Date: Thu, 19 Mar 2020 20:54:37 +0100 Subject: [PATCH 3/3] Add instagrpc package overview section to the godoc --- instrumentation/instagrpc/instagrpc.go | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 instrumentation/instagrpc/instagrpc.go diff --git a/instrumentation/instagrpc/instagrpc.go b/instrumentation/instagrpc/instagrpc.go new file mode 100644 index 000000000..a6c26634b --- /dev/null +++ b/instrumentation/instagrpc/instagrpc.go @@ -0,0 +1,3 @@ +// Package instagrpc provides Instana tracing instrumentation for +// GRPC servers and clients that use google.golang.org/grpc. +package instagrpc