updating readme

Author: nithinputhenveettil

instrumentation/instagocb/README.md

@@ -0,0 +1,106 @@
+# Instana instrumentation of Couchbase SDK v2 (gocb) for Go
+
+This module contains the code for instrumenting Couchbase SDK which are based on the [`gocb`][gocb-github] library for Go. 
+
+The following services are currently instrumented:
+
+1. Cluster
+2. Bucket
+3. Bucket Manager
+4. Collection
+5. Binary Collection
+6. Collection Manager
+7. Data Structures
+   1. List
+   2. Map
+   3. Queue
+   4. Set
+
+
+Compatibility
+-------------
+
+ * Minimum gocb version - v2.7.0 
+ * Minimum Go version - 1.13
+
+
+Installation
+------------
+
+To add the module to your `go.mod` file run the following command in your project directory:
+
+```bash
+$ go get github.com/instana/go-sensor/instrumentation/instagocb
+```
+
+Usage
+------
+
+- Instead of using `gocb.Connect`, use the `instagocb.Connect` for connecting to the couchbase server.
+  - The function defenition seems identical, excpet you need to pass an extra argument of `instana.TraceLogger` to the instagocb.Connect.
+- For each instrumented service, you will find an interface in instagocb. Use this interface instead of using th direct instances from gocb.
+  - For example, instead of `*gocb.Cluster` you need to use `instagocb.Cluster` interface.
+  - `*gocb.Collection` - `instagocb.Collection`.
+  - This applies to the all instrumented services.
+  - Don't worry too much about this, if you use instagocb.Connect, the returned cluster will be able to give you all the instrumented functionalities. Eg : If you use this `cluster.Buckets()`, it will return instrumented `instagocb.BucketManager` interface instead of `*gocb.BucketManager`.
+  - You need to set `ParentSpan` property of the `options` function argument using `instagocb.GetParentSpanFromContext(ctx)`, if your couchbase call is part of some http request or something. Else the parent-child relationship of the spans won't be tracked. (Please see the example for a full demo.)
+  - ## sample usage
+ ```go
+
+    var collector instana.TracerLogger
+    collector = instana.InitCollector(&instana.Options{
+		Service:           "sample-app-couchbase",
+		EnableAutoProfile: true,
+	}) 
+
+    // connect to database
+    // this will returns an instance of instagocb.Cluster, 
+    // which is capable of enabling instana tracing for Couchbase calls.
+	cluster, err := instagocb.Connect(collector, connectionString, gocb.ClusterOptions{
+		Authenticator: gocb.PasswordAuthenticator{
+			Username: username,
+			Password: password,
+		},
+	})
+	if err != nil {
+		// Handle error
+	}
+
+	bucket := cluster.Bucket(bucketName)
+	err = bucket.WaitUntilReady(5*time.Second, nil)
+	if err != nil {
+		// Handle error
+	}
+
+	collection := bucket.Scope("tenant_agent_00").Collection("users")
+
+	type User struct {
+		Name      string   `json:"name"`
+		Email     string   `json:"email"`
+		Interests []string `json:"interests"`
+	}
+
+	// Create and store a Document
+	_, err = col.Upsert("u:jade",
+		User{
+			Name:      "Jade",
+			Email:     "[email protected]",
+			Interests: []string{"Swimming", "Rowing"},
+		}, &gocb.UpsertOptions{
+            // If you are using couchbase call as part of some http request or something,
+            // you need to set this parentSpan property using `instagocb.GetParentSpanFromContext` method,
+            // Else the parent-child span relationship wont be tracked.
+            // You can keep this as nil, otherwise.
+            ParentSpan: instagocb.GetParentSpanFromContext(ctx)
+        })
+	if err != nil {
+		// Handle error
+	}
+
+```
+[Full example][fullExample]
+
+[fullExample]: ../../example/couchbase/main.go
+
+> [!NOTE]
+> You will find a `Unwrap()` method in all instagocb provided interfaces, it will returned the underlying gocb instance. Eg : `cluster.Unwrap()` will return an instance of `*gocb.Cluster`. Use this if you need the original instance other than the instrumented one. It is not advisable to use this directly, as Instana tracing will not be enabled if you directly utilize this instance.