Add emicklei/go-restful instrumentation

CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- Add `emicklei/go-restful/v3` trace instrumentation.
+- Update `CONTRIBUTING.md` to ask for updates to `CHANGELOG.md` with each pull request. (#114)
+- Create this `CHANGELOG.md` (#114)
+
+## [0.7.0] - 2020-06-29
+
+This release upgrades its [go.opentelemetry.io/otel](https://github.com/open-telemetry/opentelemetry-go "Otel Github") dependency to v0.7.0.
+
+### Added
+
+- Create `RELEASING.md` instructions (#101)
+- Apply transitive dependabot go.mod updates as part of a new automatic Github workflow. (#94)
+- New dependabot integration to automate package upgrades. (#61)
+- Add automatic tag generation script for release (#60)
+
+### Changed
+
+- Upgrade Datadog metrics exporter to include Resource tags (#46)
+- Added output validation to Datadog example (#96)
+- Move Macaron package to match layout guidelines. (#92)
+- Update top-level README and instrumentation README. (#92)
+- Bump google.golang.org/grpc from 1.29.1 to 1.30.0 (#99)
+- Bump github.com/golangci/golangci-lint from 1.21.0 to 1.27.0 in /tools (#77)
+- Bump go.mongodb.org/mongo-driver from 1.3.2 to 1.3.4 in /instrumentation/go.mongodb.org/mongo-driver (#76)
+- Bump github.com/stretchr/testify from 1.5.1 to 1.6.1 (#74)
+- Bump gopkg.in/macaron.v1 from 1.3.5 to 1.3.9 in /instrumentation/macaron (#68)
+- Bump github.com/gin-gonic/gin from 1.6.2 to 1.6.3 in /instrumentation/gin-gonic/gin (#73)
+- Bump github.com/DataDog/datadog-go from 3.5.0+incompatible to 3.7.2+incompatible in /exporters/metric/datadog (#78)
+
+### Removed
+
+- `internal/trace/http.go` helpers, replaced by `api/standard` helpers in otel-go repo (#112)
+
+## [0.6.1] - 2020-06-08
+
+First official tagged release of `contrib` repository.
+
+### Added
+
+- `labstack/echo` trace instrumentation (#42)
+- `mongodb` trace instrumentation (#26)
+- Go Runtime metrics (#9)
+- `gorilla/mux` trace instrumentation (#19)
+- `gin-gonic` trace instrumentation (#15)
+- `macaron` trace instrumentation (#20)
+- `dogstatsd` metrics exporter (#10)
+- `datadog` metrics exporter (#22)
+- Tags to all modules in repository
+- Repository folder structure and automated build (#3)
+
+### Changes
+
+- Prefix support for dogstatsd (#34)
+- Update Go Runtime package to use batch observer (#44)

instrumentation/emicklei/go-restful/config.go

@@ -0,0 +1,48 @@
+// 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 restful
+
+import (
+	otelpropagation "go.opentelemetry.io/otel/api/propagation"
+	oteltrace "go.opentelemetry.io/otel/api/trace"
+)
+
+// Config is used to configure the go-restful middleware.
+type Config struct {
+	Tracer      oteltrace.Tracer
+	Propagators otelpropagation.Propagators
+}
+
+// Option specifies instrumentation configuration options.
+type Option func(*Config)
+
+// WithTracer specifies a tracer to use for creating spans. If none is
+// specified, a tracer named
+// "go.opentelemetry.io/contrib/instrumentation/emicklei/go-restful" from the global
+// provider is used.
+func WithTracer(tracer oteltrace.Tracer) Option {
+	return func(cfg *Config) {
+		cfg.Tracer = tracer
+	}
+}
+
+// WithPropagators specifies propagators to use for extracting
+// information from the HTTP requests. If none are specified, global
+// ones will be used.
+func WithPropagators(propagators otelpropagation.Propagators) Option {
+	return func(cfg *Config) {
+		cfg.Propagators = propagators
+	}
+}

instrumentation/emicklei/go-restful/doc.go

@@ -0,0 +1,21 @@
+// 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 go-restful provides functions to trace the emicklei/go-restful/v3
+// package (https://github.com/emicklei/go-restful).
+//
+// Instrumentation of an incoming request is achieved via a go-restful
+// FilterFunc which may be applied at the container level, at the
+// webservice level or at a route level
+package restful // import "go.opentelemetry.io/contrib/instrumentation/emicklei/go-restful"

instrumentation/emicklei/go-restful/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:1.14-alpine AS base
+COPY . /src/
+WORKDIR /src/instrumentation/emicklei/go-restful
+
+FROM base AS go-restful-server
+RUN go install ./example/server.go
+CMD ["/go/bin/server"]

instrumentation/emicklei/go-restful/example/README.md

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

instrumentation/emicklei/go-restful/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:
+  go-restful-client:
+    image: golang:1.14-alpine
+    networks:
+      - example
+    command:
+      - "/bin/sh"
+      - "-c"
+      - "wget -O - http://go-restful-server:8080/users/123"
+    depends_on:
+      - go-restful-server
+  go-restful-server:
+    build:
+      dockerfile: $PWD/Dockerfile
+      context: ../../../..
+    ports:
+      - "8080:80"
+    command:
+      - "/bin/sh"
+      - "-c"
+      - "/go/bin/server"
+    networks:
+      - example
+networks:
+  example:

instrumentation/emicklei/go-restful/example/server.go

@@ -0,0 +1,97 @@
+// 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 (
+	"log"
+	"net/http"
+	"strconv"
+
+	"github.com/emicklei/go-restful/v3"
+
+	restfultrace "go.opentelemetry.io/contrib/instrumentation/emicklei/go-restful"
+	otelglobal "go.opentelemetry.io/otel/api/global"
+	otelkv "go.opentelemetry.io/otel/api/kv"
+	oteltrace "go.opentelemetry.io/otel/api/trace"
+	oteltracestdout "go.opentelemetry.io/otel/exporters/trace/stdout"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+)
+
+var tracer oteltrace.Tracer
+
+type UserResource struct{}
+
+func (u UserResource) WebService() *restful.WebService {
+	ws := &restful.WebService{}
+
+	ws.
+		Path("/users").
+		Consumes(restful.MIME_JSON).
+		Produces(restful.MIME_JSON)
+
+	ws.Route(ws.GET("/{user-id}").To(u.getUser).
+		Param(ws.PathParameter("user-id", "identifier of the user").DataType("integer").DefaultValue("1")).
+		Writes(User{}). // on the response
+		Returns(200, "OK", User{}).
+		Returns(404, "Not Found", nil))
+	return ws
+}
+
+func main() {
+	initTracer()
+	u := UserResource{}
+	// create the Otel filter
+	filter := restfultrace.OtelFilter("my-service")
+	// use it
+	restful.DefaultContainer.Filter(filter)
+	restful.DefaultContainer.Add(u.WebService())
+
+	_ = http.ListenAndServe(":8080", nil)
+}
+
+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)
+	tracer = otelglobal.TraceProvider().Tracer("go-restful-server", oteltrace.WithInstrumentationVersion("0.1"))
+}
+
+func (u UserResource) getUser(req *restful.Request, resp *restful.Response) {
+	uid := req.PathParameter("user-id")
+	_, span := tracer.Start(req.Request.Context(), "getUser", oteltrace.WithAttributes(otelkv.String("id", uid)))
+	defer span.End()
+	id, err := strconv.Atoi(uid)
+	if err == nil && id >= 100 {
+		_ = resp.WriteEntity(User{id})
+		return
+	}
+	_ = resp.WriteErrorString(http.StatusNotFound, "User could not be found.")
+}
+
+type User struct {
+	ID int `json:"id" description:"identifier of the user"`
+}

instrumentation/emicklei/go-restful/go.mod

@@ -0,0 +1,13 @@
+module go.opentelemetry.io/contrib/instrumentation/emicklei/go-restful
+
+go 1.14
+
+replace go.opentelemetry.io/contrib => ../../..
+
+require (
+	github.com/emicklei/go-restful/v3 v3.0.0
+	github.com/json-iterator/go v1.1.10 // indirect
+	github.com/stretchr/testify v1.6.1
+	go.opentelemetry.io/contrib v0.7.0
+	go.opentelemetry.io/otel v0.7.0
+)