diff --git a/README.md b/README.md index 3c79ba0ca34..dbfbf956da1 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,17 @@ -# opentelemetry-go-contrib +# OpenTelemetry-Go Contrib -This repo contains packages that facilitate instrumenting commonly -used libraries with OpenTelemetry for distributed tracing and -monitoring. +[![Circle CI](https://circleci.com/gh/open-telemetry/opentelemetry-go-contrib.svg?style=svg)](https://circleci.com/gh/open-telemetry/opentelemetry-go-contrib) +[![Docs](https://godoc.org/go.opentelemetry.io/contrib?status.svg)](https://pkg.go.dev/go.opentelemetry.io/contrib) +[![Go Report Card](https://goreportcard.com/badge/go.opentelemetry.io/contrib)](https://goreportcard.com/report/go.opentelemetry.io/contrib) +[![Gitter](https://badges.gitter.im/open-telemetry/opentelemetry-go.svg)](https://gitter.im/open-telemetry/opentelemetry-go?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) +Collection of 3rd-party instrumentation and exporters for [OpenTelemetry-Go](https://github.com/open-telemetry/opentelemetry-go). +## Contents + +- [Instrumentation](./instrumentation/): Packages providing OpenTelemetry instrumentation for 3rd-party libraries. +- [Exporters](./exporters/): Packages providing OpenTelemetry exporters for 3rd-party telemetry systems. + +## Contributing + +For information on how to contribute, consult [the contributing guidelines](./CONTRIBUTING.md) diff --git a/instrumentation/README.md b/instrumentation/README.md new file mode 100644 index 00000000000..7feb30cac75 --- /dev/null +++ b/instrumentation/README.md @@ -0,0 +1,37 @@ +# Instrumentation + +Code contained in this directory contains instrumentation for 3rd-party Go packages. + +## Organization + +In order to ensure the maintainability and discoverability of instrumentation packages, the following guidelines MUST be followed. + +### Packaging + +All instrumentation packages MUST be of the form: + +``` +go.opentelemetry.io/contrib/instrumentation/{PACKAGE} +``` + +Where `{PACKAGE}` is the name of 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` + +Consequentially, this means that all instrumentation MUST be contained in a sub-directory structure matching the package name. + +### Contents + +All instrumentation packages MUST adhere to [the projects' contributing guidelines](../CONTRIBUTING.md). +Additionally the following guidelines for package composition need to be followed. + +- All instrumentation packages MUST be a Go package. + Therefore, an appropriately configured `go.mod` and `go.sum` need to exist for each package. +- To help understand the instrumentation a Go package documentation SHOULD be included. + This documentation SHOULD be in a dedicated `doc.go` file if the package is more than one file. + It SHOULD contain useful information like what the purpose of the instrumentation is, how to use it, and any compatibility restrictions that might exist. +- Examples of how to actually use the instrumentation SHOULD be included. diff --git a/instrumentation/macaron/config.go b/instrumentation/gopkg.in/macaron.v1/config.go similarity index 100% rename from instrumentation/macaron/config.go rename to instrumentation/gopkg.in/macaron.v1/config.go diff --git a/instrumentation/macaron/doc.go b/instrumentation/gopkg.in/macaron.v1/doc.go similarity index 100% rename from instrumentation/macaron/doc.go rename to instrumentation/gopkg.in/macaron.v1/doc.go diff --git a/instrumentation/macaron/example/Dockerfile b/instrumentation/gopkg.in/macaron.v1/example/Dockerfile similarity index 100% rename from instrumentation/macaron/example/Dockerfile rename to instrumentation/gopkg.in/macaron.v1/example/Dockerfile diff --git a/instrumentation/macaron/example/README.md b/instrumentation/gopkg.in/macaron.v1/example/README.md similarity index 100% rename from instrumentation/macaron/example/README.md rename to instrumentation/gopkg.in/macaron.v1/example/README.md diff --git a/instrumentation/macaron/example/docker-compose.yml b/instrumentation/gopkg.in/macaron.v1/example/docker-compose.yml similarity index 100% rename from instrumentation/macaron/example/docker-compose.yml rename to instrumentation/gopkg.in/macaron.v1/example/docker-compose.yml diff --git a/instrumentation/macaron/example/server.go b/instrumentation/gopkg.in/macaron.v1/example/server.go similarity index 100% rename from instrumentation/macaron/example/server.go rename to instrumentation/gopkg.in/macaron.v1/example/server.go diff --git a/instrumentation/macaron/go.mod b/instrumentation/gopkg.in/macaron.v1/go.mod similarity index 81% rename from instrumentation/macaron/go.mod rename to instrumentation/gopkg.in/macaron.v1/go.mod index 35cff76b27f..c98d2893caf 100644 --- a/instrumentation/macaron/go.mod +++ b/instrumentation/gopkg.in/macaron.v1/go.mod @@ -2,11 +2,11 @@ module go.opentelemetry.io/contrib/instrumentation/macaron go 1.14 +replace go.opentelemetry.io/contrib => ../../.. + require ( github.com/stretchr/testify v1.5.1 go.opentelemetry.io/contrib v0.6.1 go.opentelemetry.io/otel v0.6.0 gopkg.in/macaron.v1 v1.3.5 ) - -replace go.opentelemetry.io/contrib => ../../ diff --git a/instrumentation/macaron/go.sum b/instrumentation/gopkg.in/macaron.v1/go.sum similarity index 100% rename from instrumentation/macaron/go.sum rename to instrumentation/gopkg.in/macaron.v1/go.sum diff --git a/instrumentation/macaron/macaron.go b/instrumentation/gopkg.in/macaron.v1/macaron.go similarity index 100% rename from instrumentation/macaron/macaron.go rename to instrumentation/gopkg.in/macaron.v1/macaron.go diff --git a/instrumentation/macaron/macaron_test.go b/instrumentation/gopkg.in/macaron.v1/macaron_test.go similarity index 100% rename from instrumentation/macaron/macaron_test.go rename to instrumentation/gopkg.in/macaron.v1/macaron_test.go