Add an example use of the gin-gonic instrumentation

plugins/gin-gonic/gin/example/Dockerfile

@@ -0,0 +1,20 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+FROM golang:alpine AS base
+COPY . /src/
+WORKDIR /src/plugins/gin-gonic/gin
+
+FROM base AS gin-server
+RUN go install ./example/server.go
+CMD ["/go/bin/server"]

plugins/gin-gonic/gin/example/README.md

@@ -0,0 +1,28 @@
+# gin-gonic instrumentation example
+
+An HTTP server using gin-gonic and instrumentation. The server has a
+`/users/:id` endpoint. The server generates span information to
+`stdout`.
+
+These instructions expect you have
+[docker-compose](https://docs.docker.com/compose/) installed.
+
+Bring up the `gin-server` and `gin-client` services to run the
+example:
+
+```sh
+docker-compose up --detach gin-server gin-client
+```
+
+The `gin-client` service sends just one HTTP request to `gin-server`
+and then exits. View the span generated by `gin-server` in the logs:
+
+```sh
+docker-compose logs gin-server
+```
+
+Shut down the services when you are finished with the example:
+
+```sh
+docker-compose down
+```

plugins/gin-gonic/gin/example/docker-compose.yml

@@ -0,0 +1,39 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+version: "3.7"
+services:
+  gin-client:
+    image: golang:alpine
+    networks:
+      - example
+    command:
+      - "/bin/sh"
+      - "-c"
+      - "wget http://gin-server:8080/users/123 && cat 123"
+    depends_on:
+      - gin-server
+  gin-server:
+    build:
+      dockerfile: $PWD/Dockerfile
+      context: ../../../..
+    ports:
+      - "8080:80"
+    command:
+      - "/bin/sh"
+      - "-c"
+      - "/go/bin/server"
+    networks:
+      - example
+networks:
+  example:

plugins/gin-gonic/gin/example/server.go

@@ -0,0 +1,79 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"context"
+	"html/template"
+	"log"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	gintrace "go.opentelemetry.io/contrib/plugins/gin-gonic/gin"
+	otelglobal "go.opentelemetry.io/otel/api/global"
+	otelkey "go.opentelemetry.io/otel/api/key"
+	oteltrace "go.opentelemetry.io/otel/api/trace"
+	oteltracestdout "go.opentelemetry.io/otel/exporters/trace/stdout"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+)
+
+var tracer = otelglobal.Tracer("gin-server")
+
+func main() {
+	initTracer()
+	r := gin.New()
+	r.Use(gintrace.Middleware("my-server"))
+	tmplName := "user"
+	tmplStr := "user {{ .name }} (id {{ .id }})\n"
+	tmpl := template.Must(template.New(tmplName).Parse(tmplStr))
+	r.SetHTMLTemplate(tmpl)
+	r.GET("/users/:id", func(c *gin.Context) {
+		id := c.Param("id")
+		name := getUser(c.Request.Context(), id)
+		gintrace.HTML(c, http.StatusOK, tmplName, gin.H{
+			"name": name,
+			"id":   id,
+		})
+	})
+	_ = r.Run(":8080")
+}
+
+func initTracer() {
+	exporter, err := oteltracestdout.NewExporter(oteltracestdout.Options{PrettyPrint: true})
+	if err != nil {
+		log.Fatal(err)
+	}
+	cfg := sdktrace.Config{
+		DefaultSampler: sdktrace.AlwaysSample(),
+	}
+	tp, err := sdktrace.NewProvider(
+		sdktrace.WithConfig(cfg),
+		sdktrace.WithSyncer(exporter),
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+	otelglobal.SetTraceProvider(tp)
+}
+
+func getUser(ctx context.Context, id string) string {
+	_, span := tracer.Start(ctx, "getUser", oteltrace.WithAttributes(otelkey.String("id", id)))
+	defer span.End()
+	if id == "123" {
+		return "gintrace tester"
+	}
+	return "unknown"
+}