chore: An example of instrumenting a gRPC client and server with Inst…

…ana using instagrpc (#975)

* chore: an example of instrumenting a gRPC client and server with Instana using instagrpc

example/grpc/README.md

@@ -0,0 +1,29 @@
+# An Example For gRPC Instrumentation
+============================
+
+An example of instrumenting a gRPC client and server with Instana using [`github.com/instana/go-sensor/tree/main/instrumentation/instagrpc`](https://pkg.go.dev/github.com/instana/go-sensor/instrumentation/instagrpc).
+
+
+## Usage
+
+Install the packages 
+
+```bash
+go mod tidy
+```
+
+Start the gRPC Server:
+
+```bash
+go run server/main.go
+```
+
+Run the gRPC client
+
+```bash
+go run client/main.go
+```
+
+## Output
+
+The client makes a unary, stream and an unknown call to the gRPC server. You will be able to see those 3 call traces in the Instana dashboard.

example/grpc/client/main.go

@@ -0,0 +1,119 @@
+// (c) Copyright IBM Corp. 2024
+
+//go:build go1.22
+// +build go1.22
+
+package main
+
+import (
+	"context"
+	"io"
+	"log"
+	"time"
+
+	instana "github.com/instana/go-sensor"
+	pb "github.com/instana/go-sensor/example/grpc/hellopb"
+	"github.com/instana/go-sensor/instrumentation/instagrpc"
+	"github.com/opentracing/opentracing-go/ext"
+	"google.golang.org/grpc"
+)
+
+func main() {
+
+	sensor := instana.NewSensor("grpc-client")
+
+	// Connect to the server.
+	conn, err := grpc.Dial("localhost:50051",
+		grpc.WithInsecure(),
+		grpc.WithUnaryInterceptor(instagrpc.UnaryClientInterceptor(sensor)),
+		grpc.WithStreamInterceptor(instagrpc.StreamClientInterceptor(sensor)))
+	if err != nil {
+		log.Fatalf("Failed to connect: %v", err)
+	}
+	defer conn.Close()
+
+	client := pb.NewGreeterClient(conn)
+
+	// Unary call
+	doUnaryCall(sensor, client)
+
+	// Server-side streaming call
+	doStreamingCall(sensor, client)
+
+	// Make a call to an unknown service/method.
+	doUnknownServiceCall(sensor, conn)
+
+	time.Sleep(10 * time.Minute)
+}
+
+func doUnknownServiceCall(sensor instana.TracerLogger, client *grpc.ClientConn) {
+
+	sp := sensor.Tracer().
+		StartSpan("grpc-unknown-service-call").
+		SetTag(string(ext.SpanKind), "entry")
+
+	sp.Finish()
+
+	ctx := instana.ContextWithSpan(context.Background(), sp)
+
+	// Invoke a non-existent method (this will trigger the UnknownServiceHandler).
+	err := client.Invoke(ctx, "/UnknownService/UnknownMethod", nil, nil)
+	if err != nil {
+		log.Printf("Error from server: %v", err)
+	} else {
+		log.Println("Call succeeded (unexpected).")
+	}
+}
+
+func doUnaryCall(sensor instana.TracerLogger, client pb.GreeterClient) {
+
+	sp := sensor.Tracer().
+		StartSpan("grpc-unary-client-call").
+		SetTag(string(ext.SpanKind), "entry")
+
+	sp.Finish()
+
+	ctx := instana.ContextWithSpan(context.Background(), sp)
+
+	log.Println("Starting Unary Call...")
+	ctx, cancel := context.WithTimeout(ctx, time.Second)
+	defer cancel()
+
+	resp, err := client.SayHello(ctx, &pb.HelloRequest{Name: "World"})
+	if err != nil {
+		log.Fatalf("Unary call failed: %v", err)
+	}
+	log.Printf("Unary Response: %s", resp.GetMessage())
+}
+
+func doStreamingCall(sensor instana.TracerLogger, client pb.GreeterClient) {
+
+	sp := sensor.Tracer().
+		StartSpan("grpc-stream-client-call").
+		SetTag(string(ext.SpanKind), "entry")
+
+	sp.Finish()
+
+	ctx := instana.ContextWithSpan(context.Background(), sp)
+
+	log.Println("Starting Streaming Call...")
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+
+	stream, err := client.SayHelloStream(ctx, &pb.HelloRequest{Name: "World"})
+	if err != nil {
+		log.Fatalf("Streaming call failed: %v", err)
+	}
+
+	for {
+		resp, err := stream.Recv()
+		if err == io.EOF {
+			log.Println("Streaming completed.")
+			break
+		}
+		if err != nil {
+			log.Fatalf("Error receiving stream: %v", err)
+		}
+		log.Printf("Streaming Response: %s", resp.GetMessage())
+	}
+}

example/grpc/go.mod

@@ -0,0 +1,20 @@
+module github.com/instana/go-sensor/example/grpc
+
+go 1.22.7
+
+require (
+	github.com/instana/go-sensor v1.65.0
+	github.com/instana/go-sensor/instrumentation/instagrpc v1.29.0
+	github.com/opentracing/opentracing-go v1.2.0
+	google.golang.org/grpc v1.68.0
+	google.golang.org/protobuf v1.35.2
+)
+
+require (
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/looplab/fsm v1.0.1 // indirect
+	golang.org/x/net v0.29.0 // indirect
+	golang.org/x/sys v0.25.0 // indirect
+	golang.org/x/text v0.18.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20240903143218-8af14fe29dc1 // indirect
+)

example/grpc/go.sum

@@ -0,0 +1,37 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/instana/go-sensor v1.65.0 h1:tvghnyNsSE2Bj1nsARLwLFc7GIR9+NXN7QAjMRw6EHg=
+github.com/instana/go-sensor v1.65.0/go.mod h1:Ngi6H3q4iZ6yn4EH9zQYUflI/eDTULrM3B+RW9HN4zI=
+github.com/instana/go-sensor/instrumentation/instagrpc v1.29.0 h1:YwdOePmbhNS2tGp1zfsdfl6ZxjKw5D79m3i7YyUVkbI=
+github.com/instana/go-sensor/instrumentation/instagrpc v1.29.0/go.mod h1:7nSl2l6iVw75UnW5oIe3q0CFEUGJ+z+4sjmir3GnWAg=
+github.com/looplab/fsm v1.0.1 h1:OEW0ORrIx095N/6lgoGkFkotqH6s7vaFPsgjLAaF5QU=
+github.com/looplab/fsm v1.0.1/go.mod h1:PmD3fFvQEIsjMEfvZdrCDZ6y8VwKTwWNjlpEr6IKPO4=
+github.com/opentracing/opentracing-go v1.2.0 h1:uEJPy/1a5RIPAJ0Ov+OIO8OxWu77jEv+1B0VhjKrZUs=
+github.com/opentracing/opentracing-go v1.2.0/go.mod h1:GxEUsuufX4nBwe+T+Wl9TAgYrxe9dPLANfrWvHYVTgc=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+golang.org/x/net v0.29.0 h1:5ORfpBpCs4HzDYoodCDBbwHzdR5UrLBZ3sOnUJmFoHo=
+golang.org/x/net v0.29.0/go.mod h1:gLkgy8jTGERgjzMic6DS9+SP0ajcu6Xu3Orq/SpETg0=
+golang.org/x/sys v0.25.0 h1:r+8e+loiHxRqhXVl6ML1nO3l1+oFoWbnlu2Ehimmi34=
+golang.org/x/sys v0.25.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/text v0.18.0 h1:XvMDiNzPAl0jr17s6W9lcaIhGUfUORdGCNsuLmPG224=
+golang.org/x/text v0.18.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20240903143218-8af14fe29dc1 h1:pPJltXNxVzT4pK9yD8vR9X75DaWYYmLGMsEvBfFQZzQ=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20240903143218-8af14fe29dc1/go.mod h1:UqMtugtsSgubUsoxbuAoiCXvqvErP7Gf0so0mK9tHxU=
+google.golang.org/grpc v1.68.0 h1:aHQeeJbo8zAkAa3pRzrVjZlbz6uSfeOXlJNQM0RAbz0=
+google.golang.org/grpc v1.68.0/go.mod h1:fmSPC5AsjSBCK54MyHRx48kpOti1/jRfOlwEWywNjWA=
+google.golang.org/protobuf v1.35.2 h1:8Ar7bF+apOIoThw1EdZl0p1oWvMqTHmpA2fRTyZO8io=
+google.golang.org/protobuf v1.35.2/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=