Update instrumentation naming

.github/dependabot.yml

@@ -99,7 +99,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/astaxie/beego"
+    directory: "/instrumentation/github.com/astaxie/beego/otelbeego"
     labels:
       - dependencies
       - go
@@ -109,7 +109,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/astaxie/beego/example"
+    directory: "/instrumentation/github.com/astaxie/beego/otelbeego/example"
     labels:
       - dependencies
       - go
@@ -119,7 +119,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/bradfitz/gomemcache"
+    directory: "/instrumentation/github.com/bradfitz/gomemcache/memcache/otelmemcache"
     labels:
       - dependencies
       - go
@@ -129,7 +129,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/emicklei/go-restful"
+    directory: "/instrumentation/github.com/emicklei/go-restful/otelrestful"
     labels:
       - dependencies
       - go
@@ -139,7 +139,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/gin-gonic/gin"
+    directory: "/instrumentation/github.com/gin-gonic/gin/otelgin"
     labels:
       - dependencies
       - go
@@ -149,7 +149,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/gocql/gocql"
+    directory: "/instrumentation/github.com/gocql/gocql/otelgocql"
     labels:
       - dependencies
       - go
@@ -159,7 +159,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/gocql/gocql/example"
+    directory: "/instrumentation/github.com/gocql/gocql/otelgocql/example"
     labels:
       - dependencies
       - go
@@ -169,7 +169,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/gorilla/mux"
+    directory: "/instrumentation/github.com/gorilla/mux/otelmux"
     labels:
       - dependencies
       - go
@@ -179,7 +179,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/labstack/echo"
+    directory: "/instrumentation/github.com/labstack/echo/otelecho"
     labels:
       - dependencies
       - go
@@ -189,7 +189,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/Shopify/sarama"
+    directory: "/instrumentation/github.com/Shopify/sarama/otelsarama"
     labels:
       - dependencies
       - go
@@ -199,7 +199,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/github.com/Shopify/sarama/example"
+    directory: "/instrumentation/github.com/Shopify/sarama/otelsarama/example"
     labels:
       - dependencies
       - go
@@ -209,7 +209,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/go.mongodb.org/mongo-driver"
+    directory: "/instrumentation/go.mongodb.org/mongo-driver/mongo/otelmongo"
     labels:
       - dependencies
       - go
@@ -219,7 +219,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/google.golang.org/grpc"
+    directory: "/instrumentation/google.golang.org/grpc/otelgrpc"
     labels:
       - dependencies
       - go
@@ -229,7 +229,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/google.golang.org/grpc/example"
+    directory: "/instrumentation/google.golang.org/grpc/otelgrpc/example"
     labels:
       - dependencies
       - go
@@ -239,7 +239,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/gopkg.in/macaron.v1"
+    directory: "/instrumentation/gopkg.in/macaron.v1/otelmacaron"
     labels:
       - dependencies
       - go
@@ -259,7 +259,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/net/http"
+    directory: "/instrumentation/net/http/otelhttp"
     labels:
       - dependencies
       - go
@@ -269,7 +269,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/net/http/example"
+    directory: "/instrumentation/net/http/otelhttp/example"
     labels:
       - dependencies
       - go
@@ -279,7 +279,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/net/http/httptrace"
+    directory: "/instrumentation/net/http/httptrace/otelhttptrace"
     labels:
       - dependencies
       - go
@@ -289,7 +289,7 @@ updates:
       day: "sunday"
   -
     package-ecosystem: "gomod"
-    directory: "/instrumentation/net/http/httptrace/example"
+    directory: "/instrumentation/net/http/httptrace/otelhttptrace/example"
     labels:
       - dependencies
       - go

.gitignore

@@ -9,6 +9,6 @@ Thumbs.db
 coverage.*
 
 exporters/metric/cortex/example/example
-instrumentation/github.com/gocql/gocql/example/example
-instrumentation/google.golang.org/grpc/example/server/server
-instrumentation/google.golang.org/grpc/example/client/client
+instrumentation/github.com/gocql/gocql/otelgocql/example/example
+instrumentation/google.golang.org/grpc/otelgrpc/example/server/server
+instrumentation/google.golang.org/grpc/otelgrpc/example/client/client

CHANGELOG.md

@@ -23,6 +23,20 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Make config struct of instrumentation unexported. (#303)
 - Instrumentations have been updated to adhere to the [configuration style guide's](https://github.com/open-telemetry/opentelemetry-go/blob/master/CONTRIBUTING.md#config)
    updated recommendation to use `newConfig()` instead of `configure()`. (#336)
+- A new instrumentation naming scheme is implemented to avoid package name conflicts for instrumented packages while still remaining discoverable. (#359)
+  - `google.golang.org/grpc` -> `google.golang.org/grpc/otelgrpc`
+  - `go.mongodb.org/mongo-driver` -> `go.mongodb.org/mongo-driver/mongo/otelmongo`
+  - `net/http` -> `net/http/otelhttp`
+  - `net/http/httptrace` -> `net/http/httptrace/otelhttptrace`
+  - `github.com/labstack/echo` -> `github.com/labstack/echo/otelecho`
+  - `github.com/bradfitz/gomemcache` -> `github.com/bradfitz/gomemcache/memcache/otelmemcache`
+  - `github.com/gin-gonic/gin` -> `github.com/gin-gonic/gin/otelgin`
+  - `github.com/gocql/gocql` -> `github.com/gocql/gocql/otelgocql`
+  - `github.com/emicklei/go-restful` -> `github.com/emicklei/go-restful/otelrestful`
+  - `github.com/Shopify/sarama` -> `github.com/Shopify/sarama/otelsarama`
+  - `github.com/gorilla/mux` -> `github.com/gorilla/mux/otelmux`
+  - `github.com/astaxie/beego` -> `github.com/astaxie/beego/otelbeego`
+  - `gopkg.in/macaron.v1` -> `gopkg.in/macaron.v1/otelmacaron`
 
 ## [0.11.0] - 2020-08-25
 

Makefile

@@ -60,7 +60,7 @@ test-gocql:
 	  set -e; \
 	  docker run --name cass-integ --rm -p 9042:9042 -d cassandra:3; \
 	  CMD=cassandra IMG_NAME=cass-integ ./.circleci/wait.sh; \
-	  (cd instrumentation/github.com/gocql/gocql && \
+	  (cd instrumentation/github.com/gocql/gocql/otelgocql && \
 	    $(GOTEST_WITH_COVERAGE) . && \
 	    go tool cover -html=coverage.txt -o coverage.html); \
 	  docker stop cass-integ; \
@@ -72,7 +72,7 @@ test-mongo-driver:
 	  set -e; \
 	  docker run --name mongo-integ --rm -p 27017:27017 -d mongo; \
 	  CMD=mongo IMG_NAME=mongo-integ ./.circleci/wait.sh; \
-	  (cd instrumentation/go.mongodb.org/mongo-driver && \
+	  (cd instrumentation/go.mongodb.org/mongo-driver/mongo/otelmongo && \
 	    $(GOTEST_WITH_COVERAGE) . && \
 	    go tool cover -html=coverage.txt -o coverage.html); \
 	  docker stop mongo-integ; \
@@ -84,7 +84,7 @@ test-gomemcache:
 	  set -e; \
 	  docker run --name gomemcache-integ --rm -p 11211:11211 -d memcached; \
 	  CMD=gomemcache IMG_NAME=gomemcache-integ  ./.circleci/wait.sh; \
-	  (cd instrumentation/github.com/bradfitz/gomemcache && \
+	  (cd instrumentation/github.com/bradfitz/gomemcache/memcache/otelmemcache && \
 	    $(GOTEST_WITH_COVERAGE) . && \
 	    go tool cover -html=coverage.txt -o coverage.html); \
 	  docker stop gomemcache-integ ; \

instrumentation/README.md

@@ -8,21 +8,22 @@ In order to ensure the maintainability and discoverability of instrumentation pa
 
 ### Packaging
 
-All instrumentation packages MUST be of the form:
+All instrumentation packages SHOULD be of the form:
 
 ```
-go.opentelemetry.io/contrib/instrumentation/{PACKAGE}
+go.opentelemetry.io/contrib/instrumentation/{IMPORT_PATH}/otel{PACKAGE_NAME}
 ```
 
-Where `{PACKAGE}` is the name of the package being instrumented.
+Where the [`{IMPORT_PATH}`](https://golang.org/ref/spec#ImportPath) and [`{PACKAGE_NAME}`](https://golang.org/ref/spec#PackageName) are the standard Go identifiers for the package being instrumented.
 
 For example:
 
-- `go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux`
-- `go.opentelemetry.io/contrib/instrumentation/gopkg.in/macaron.v1`
-- `go.opentelemetry.io/contrib/instrumentation/database/sql`
+- `go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux`
+- `go.opentelemetry.io/contrib/instrumentation/gopkg.in/macaron.v1/otelmacaron`
+- `go.opentelemetry.io/contrib/instrumentation/database/sql/otelsql`
 
-Consequentially, this means that all instrumentation MUST be contained in a sub-directory structure matching the package name.
+Exceptions to this rule do exist.
+For example, the [runtime](./runtime) instrumentation does not instrument a Go package and does not fit this structure.
 
 ### Contents
 

instrumentation/github.com/Shopify/sarama/consumer.go → instrumentation/github.com/Shopify/sarama/otelsarama/consumer.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package sarama
+package otelsarama
 
 import (
 	"github.com/Shopify/sarama"

instrumentation/github.com/Shopify/sarama/consumer_group.go → instrumentation/github.com/Shopify/sarama/otelsarama/consumer_group.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package sarama
+package otelsarama
 
 import (
 	"github.com/Shopify/sarama"

instrumentation/github.com/Shopify/sarama/consumer_group_test.go → instrumentation/github.com/Shopify/sarama/otelsarama/consumer_group_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package sarama
+package otelsarama
 
 // TODO: add test for consumer group
 // Currently, sarama does not have a mock consumer group, so it's hard to

instrumentation/github.com/Shopify/sarama/consumer_test.go → instrumentation/github.com/Shopify/sarama/otelsarama/consumer_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package sarama
+package otelsarama
 
 import (
 	"context"

instrumentation/github.com/Shopify/sarama/dispatcher.go → instrumentation/github.com/Shopify/sarama/otelsarama/dispatcher.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package sarama
+package otelsarama
 
 import (
 	"context"

instrumentation/github.com/Shopify/sarama/doc.go → instrumentation/github.com/Shopify/sarama/otelsarama/doc.go

@@ -12,12 +12,12 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package sarama provides functions to trace the Shopify/sarama package. (https://github.com/Shopify/sarama)
+// Package otelsarama instruments the github.com/Shopify/sarama package.
 //
 // The consumer's span will be created as a child of the producer's span.
 //
 // Context propagation only works on Kafka versions higher than 0.11.0.0 which supports record headers.
 // (https://archive.apache.org/dist/kafka/0.11.0.0/RELEASE_NOTES.html)
 //
 // Based on: https://github.com/DataDog/dd-trace-go/tree/v1/contrib/Shopify/sarama
-package sarama // import "go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama"
+package otelsarama // import "go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama/otelsarama"

instrumentation/github.com/Shopify/sarama/example/consumer/Dockerfile → instrumentation/github.com/Shopify/sarama/otelsarama/example/consumer/Dockerfile

@@ -13,9 +13,9 @@
 # limitations under the License.
 FROM golang:alpine AS base
 COPY . /src/
-WORKDIR /src/instrumentation/github.com/Shopify/sarama
+WORKDIR /src/instrumentation/github.com/Shopify/sarama/otelsarama/example
 
 FROM base AS kafka-consumer
-RUN go install ./example/consumer/consumer.go
+RUN go install ./consumer/consumer.go
 CMD ["/go/bin/consumer"]
 

instrumentation/github.com/Shopify/sarama/example/consumer/consumer.go → instrumentation/github.com/Shopify/sarama/otelsarama/example/consumer/consumer.go

@@ -29,8 +29,8 @@ import (
 	"go.opentelemetry.io/otel/api/trace"
 	"go.opentelemetry.io/otel/semconv"
 
-	saramatrace "go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama"
-	"go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama/example"
+	"go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama/otelsarama"
+	"go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama/otelsarama/example"
 )
 
 var (
@@ -57,7 +57,7 @@ func main() {
 func startConsumerGroup(brokerList []string) {
 	consumerGroupHandler := Consumer{}
 	// Wrap instrumentation
-	handler := saramatrace.WrapConsumerGroupHandler(&consumerGroupHandler)
+	handler := otelsarama.WrapConsumerGroupHandler(&consumerGroupHandler)
 
 	config := sarama.NewConfig()
 	config.Version = sarama.V2_5_0_0
@@ -77,7 +77,7 @@ func startConsumerGroup(brokerList []string) {
 
 func printMessage(msg *sarama.ConsumerMessage) {
 	// Extract tracing info from message
-	ctx := propagation.ExtractHTTP(context.Background(), global.Propagators(), saramatrace.NewConsumerMessageCarrier(msg))
+	ctx := propagation.ExtractHTTP(context.Background(), global.Propagators(), otelsarama.NewConsumerMessageCarrier(msg))
 
 	tr := global.Tracer("consumer")
 	_, span := tr.Start(ctx, "consume message", trace.WithAttributes(

instrumentation/github.com/Shopify/sarama/example/docker-compose.yml → instrumentation/github.com/Shopify/sarama/otelsarama/example/docker-compose.yml

@@ -46,7 +46,7 @@ services:
   kafka-producer:
     build:
       dockerfile: $PWD/producer/Dockerfile
-      context: ../../../../..
+      context: ../../../../../..
     command:
       - "/bin/sh"
       - "-c"
@@ -60,7 +60,7 @@ services:
   kafka-consumer:
     build:
       dockerfile: $PWD/consumer/Dockerfile
-      context: ../../../../..
+      context: ../../../../../..
     command:
       - "/bin/sh"
       - "-c"

instrumentation/github.com/Shopify/sarama/example/go.mod → instrumentation/github.com/Shopify/sarama/otelsarama/example/go.mod

@@ -1,14 +1,14 @@
-module go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama/example
+module go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama/otelsarama/example
 
 go 1.14
 
-replace go.opentelemetry.io/contrib => ../../../../..
+replace go.opentelemetry.io/contrib => ../../../../../..
 
-replace go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama => ../
+replace go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama/otelsarama => ../
 
 require (
 	github.com/Shopify/sarama v1.27.0
-	go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama v0.11.0
+	go.opentelemetry.io/contrib/instrumentation/github.com/Shopify/sarama/otelsarama v0.11.0
 	go.opentelemetry.io/otel v0.11.0
 	go.opentelemetry.io/otel/exporters/stdout v0.11.0
 	go.opentelemetry.io/otel/sdk v0.11.0