Given that this contrib repo has a version dependency on the go.opentelemetry.io/otel repo as well as its own version (which may or may not be the same as the otel repo version), we likely need:

• RELEASING.md
• tag.sh
• verify_examples.sh
  to ensure we release correctly tagged and verified releases.

Since release https://github.com/open-telemetry/opentelemetry-go/releases/tag/v0.4.3 the library has changed its exporter API to pass a *resource.Resource object through the pipeline. These are the static key:value labels that were configured with the SDK. They should be included as labels in any metric and span export.

There is an opportunity to compute a []string for these once and re-use it. The exporter should compute this caching on the first call to Export.

@marwan-at-work FYI

Related change log:

This release implements the v0.5.0 version of the OpenTelemetry specification.

Added

• The othttp instrumentation now includes default metrics. (#861)
• This CHANGELOG file to track all changes in the project going forward.
• Support for array type attributes. (#798)
• Apply transitive dependabot go.mod dependency updates as part of a new automatic Github workflow. (#844)
• Timestamps are now passed to exporters for each export. (#835)
• Add new Accumulation type to metric SDK to transport telemetry from Accumulators to Processors.
  This replaces the prior Record struct use for this purpose. (#835)
• New dependabot integration to automate package upgrades. (#814)
• Meter and Tracer implementations accept instrumentation version version as an optional argument.
  This instrumentation version is passed on to exporters. (#811) (#805) (#802)
• The OTLP exporter includes the instrumentation version in telemetry it exports. (#811)
• Environment variables for Jaeger exporter are supported. (#796)
• New aggregation.Kind in the export metric API. (#808)
• New example that uses OTLP and the collector. (#790)
• Handle errors in the span SetName during span initialization. (#791)
• Default service config to enable retries for retry-able failed requests in the OTLP exporter and an option to override this default. (#777)
• New go.opentelemetry.io/otel/api/oterror package to uniformly support error handling and definitions for the project. (#778)
• New global default implementation of the go.opentelemetry.io/otel/api/oterror.Handler interface to be used to handle errors prior to an user defined Handler.
  There is also functionality for the user to register their Handler as well as a convenience function Handle to handle an error with this global Handler(#778)
• Options to specify propagators for httptrace and grpctrace instrumentation. (#784)
• The required application/json header for the Zipkin exporter is included in all exports. (#774)
• Integrate HTTP semantics helpers from the contrib repository into the api/standard package. #769

Changed

• Rename Integrator to Processor in the metric SDK. (#863)
• Rename AggregationSelector to AggregatorSelector. (#859)
• Rename SynchronizedCopy to SynchronizedMove. (#858)
• Rename simple integrator to basic integrator. (#857)
• Merge otlp collector examples. (#841)
• Change the metric SDK to support cumulative, delta, and pass-through exporters directly.
  With these changes, cumulative and delta specific exporters are able to request the correct kind of aggregation from the SDK. (#840)
• The Aggregator.Checkpoint API is renamed to SynchronizedCopy and adds an argument, a different Aggregator into which the copy is stored. (#812)
• The export.Aggregator contract is that Update() and SynchronizedCopy() are synchronized with each other.
  All the aggregation interfaces (Sum, LastValue, ...) are not meant to be synchronized, as the caller is expected to synchronize aggregators at a higher level after the Accumulator.
  Some of the Aggregators used unnecessary locking and that has been cleaned up. (#812)
• Use of metric.Number was replaced by int64 now that we use sync.Mutex in the MinMaxSumCount and Histogram Aggregators. (#812)
• Replace AlwaysParentSample with ParentSample(fallback) to match the OpenTelemetry v0.5.0 specification. (#810)
• Rename sdk/export/metric/aggregator to sdk/export/metric/aggregation. #808
• Send configured headers with every request in the OTLP exporter, instead of just on connection creation. (#806)
• Update error handling for any one off error handlers, replacing, instead, with the global.Handle function. (#791)
• Rename plugin directory to instrumentation to match the OpenTelemetry specification. (#779)
• Makes the argument order to Histogram and DDSketch New() consistent. (#781)

Removed

• Uint64NumberKind and related functions from the API. (#864)
• Context arguments from Aggregator.Checkpoint and Integrator.Process as they were unused. (#803)
• SpanID is no longer included in parameters for sampling decision to match the OpenTelemetry specification. (#775)

Fixed

• Upgrade OTLP exporter to opentelemetry-proto matching the opentelemetry-collector v0.4.0 release. (#866)
• Allow changes to go.sum and go.mod when running dependabot tidy-up. (#871)
• Bump github.com/stretchr/testify from 1.4.0 to 1.6.1. (#824)
• Bump github.com/prometheus/client_golang from 1.7.0 to 1.7.1 in /exporters/metric/prometheus. (#867)
• Bump google.golang.org/grpc from 1.29.1 to 1.30.0 in /exporters/trace/jaeger. (#853)
• Bump google.golang.org/grpc from 1.29.1 to 1.30.0 in /exporters/trace/zipkin. (#854)
• Bumps github.com/golang/protobuf from 1.3.2 to 1.4.2 (#848)
• Bump github.com/stretchr/testify from 1.4.0 to 1.6.1 in /exporters/otlp (#817)
• Bump github.com/golangci/golangci-lint from 1.25.1 to 1.27.0 in /tools (#828)
• Bump github.com/prometheus/client_golang from 1.5.0 to 1.7.0 in /exporters/metric/prometheus (#838)
• Bump github.com/stretchr/testify from 1.4.0 to 1.6.1 in /exporters/trace/jaeger (#829)
• Bump github.com/benbjohnson/clock from 1.0.0 to 1.0.3 (#815)
• Bump github.com/stretchr/testify from 1.4.0 to 1.6.1 in /exporters/trace/zipkin (#823)
• Bump github.com/itchyny/gojq from 0.10.1 to 0.10.3 in /tools (#830)
• Bump github.com/stretchr/testify from 1.4.0 to 1.6.1 in /exporters/metric/prometheus (#822)
• Bump google.golang.org/grpc from 1.27.1 to 1.29.1 in /exporters/trace/zipkin (#820)
• Bump google.golang.org/grpc from 1.27.1 to 1.29.1 in /exporters/trace/jaeger (#831)
• Bump github.com/google/go-cmp from 0.4.0 to 0.5.0 (#836)
• Bump github.com/google/go-cmp from 0.4.0 to 0.5.0 in /exporters/trace/jaeger (#837)
• Bump github.com/google/go-cmp from 0.4.0 to 0.5.0 in /exporters/otlp (#839)
• Bump google.golang.org/api from 0.20.0 to 0.28.0 in /exporters/trace/jaeger (#843)
• Set span status from HTTP status code in the othttp instrumentation. (#832)
• Fixed typo in push controller comment. (#834)
• The Aggregator testing has been updated and cleaned. (#812)
• metric.Number(0) expressions are replaced by 0 where possible. (#812)
• Fixed global handler_test.go test failure. #804
• Fixed BatchSpanProcessor.Shutdown to wait until all spans are processed. (#766)
• Fixed OTLP example's accidental early close of exporter. (#807)
• Ensure zipkin exporter reads and closes response body. (#788)
• Update instrumentation to use api/standard keys instead of custom keys. (#782)
• Clean up tools and RELEASING documentation. (#762)

https://github.com/streadway/amqp

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/opentracing-contrib/go-amqp

Noticed that the coverage.html artifact produced in the CircleCI build reports on coverage only for internal/trace/... files in the main module.

There is no coverage reported for any of the contributed package source files.

https://github.com/uber-go/zap

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/opentracing-contrib/go-zap

The new statsd exporter looks for a LastValue aggregator to emit gauge metrics. This is problematic because the NewExportPipeline factory uses simple.NewWithExactMeasure as its aggregator selector. This selector chooses the points aggregation for Observer types.

func (selectorExact) AggregatorFor(descriptor *metric.Descriptor) export.Aggregator {
	switch descriptor.MetricKind() {
	case metric.ObserverKind:
		fallthrough
	case metric.MeasureKind:
		return array.New()
	default:
		return sum.New()
	}
}

In most cases, I would imagine those using DataDog would expect Observer results to be output as traditional gauge metrics. The recommendation here says

This also allows aggregating over time to export a distribution, but the "last" value is still well defined in each collection interval for a given label set. I imagine that an exporter that wants traditional gauge semantics could just export the sum, under the assumption that count==1, and that would be all that's needed.

However, this exporter does not consider this. Also IIUC under certain circumstances (e.g. short push interval, and low traffic) there may be situations where true histogram values come in with a single count. In that case it would be impossible to determine what is desired to be exported as a gauge, vs. what is desired to be exported as a histogram.

In light of this, the two solutions I see are to make the ExactMeasure selector choose a LastValue aggregator for the metric.ObserverKind case, or provide the ability to construct our own export pipeline with out own selector. The latter is currently not possible because Exporter.labelEncoder is not present.

If a new selector is in fact required, I think it makes sense to add to this library since the exporter expects a LastValue aggregator to be used.

@jmacd I'll defer to you here on any options I probably missed since you're most familiar in this space.

Like #23 but for dogstatsd exporter.

See

Usually the name/version of the trace.Tracer is something that the instrumentation library should control, but we should allow configuring the trace.Provider.

This issue comes from #153 to track the missing test for the Sarama consumer group.

Currently, sarama does not have a mock consumer group, so it's hard to write a unit test.

Sarama issue: IBM/sarama#1767
Possible implements of mock consumer group: IBM/sarama#1750

https://github.com/bradfitz/gomemcache

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/DataDog/dd-trace-go/tree/v1/contrib/bradfitz/gomemcache/memcache

Create a CHANGELOG.md that documents changes between versions.

See open-telemetry/opentelemetry-go#974.

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

https://github.com/go-redis/redis

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/opentracing-contrib/goredis
• https://github.com/DataDog/dd-trace-go/tree/v1/contrib/go-redis/redis
• https://github.com/opencensus-integrations/redis

The gRPC instrumentation ...

• should include metric instruments to capture metric events.
  • prior art: https://godoc.org/go.opencensus.io/plugin/ocgrpc#pkg-variables
  • should act as a prototype for OpenTelemetry.
• rename to not include trace in name. Likely want to follow the naming standards from the contrib instrumentation: go.opentelemetry.io/otel/instrumentation/google.golang.org/grpc (though IIRC there are more than one gRPC libraries this works with 🤷).
• make into its own Go module to separate it from the go.opentelemetry.io/otel (specifically go.opentelemetry.io/otel/api) package.
• investigate if this should be moved to the contrib repository.

#118 broke our dependabot updates for some plugins

https://github.com/emicklei/go-restful

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/opentracing-contrib/go-restful
• https://github.com/DataDog/dd-trace-go/tree/v1/contrib/emicklei/go-restful

This repo has a copy of the trace testing helpers from the main repository. This repo does not have a copy of the metric testing helpers. We should add test helpers to support testing metrics in this repository, but first some code should be exposed from the main repository (e.g., AsyncInstrumentState).

Our instrumentation naming convention is well structured to find appropriate instrumentation, but the duplication of the package name is guaranteed to cause collision with the package users are instrumenting.

Options

1. Leave it as is and let the user deal with package naming overrides.
2. Add a suffix of otel to the declared package in the Go code, but leave the import naming (and directory structure) unchanged. This means that

   import "go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux"
   

   would be named

   package muxotel
   

3. Change the declared package name like (2), but also rename the final directory name (if it is the same as the package name) to have an otel suffix
   • go.opentelemetry.io/contrib/instrumentation/runtime -> go.opentelemetry.io/contrib/instrumentation/runtimeotel
   • go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux -> go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/muxotel
   • go.opentelemetry.io/contrib/instrumentation/gopkg.in/macaron.v1 -> go.opentelemetry.io/contrib/instrumentation/gopkg.in/macaron.v1 (doesn't change given the directory doesn't match the macaron package name).
4. Change the declared package name like (2), but also add an additional directory with the instrumented library package name and a suffix of otel.
   • go.opentelemetry.io/contrib/instrumentation/runtime -> go.opentelemetry.io/contrib/instrumentation/runtime/runtimeotel
   • go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux -> go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/muxotel
   • go.opentelemetry.io/contrib/instrumentation/gopkg.in/macaron.v1 -> go.opentelemetry.io/contrib/instrumentation/gopkg.in/macaron.v1/macaronotel

Analysis/Recommendation

Option (1) treats this as a non-issue. From user the feedback we have received and based on the conversation in today's SIG meeting, this seems like an issue.

Option (2) benefits from slightly less verbosity in the import name, but has the downside that the import name will not match the package name. This name mismatch will be undesired by new users.

Option (3) modifies the import name possibly making it slightly less clear (if you were to do a text search for instance) of a discovery process. However, it is also slightly less verbose.

Option (4) is the most verbose.

With the primary goals being:

• Discoverability: It should be easy to search or explore the repo to find instrumentation.
• Usability: Cause the least amount of frustration to the end user or unexpected behaviour.

I think Option (4) is the correct choice. The downside of it being verbose and therefore impacting usability seems comparatively minor to the other usability issues of the other options. Especially if, as is common, tooling is used to actually write import names.

It's good to see support for database/sql driver. We've some discussion here open-telemetry/opentelemetry-go#490.

https://github.com/aws/aws-sdk-go

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/opentracing-contrib/go-aws-sdk
• https://github.com/DataDog/dd-trace-go/tree/v1/contrib/aws/aws-sdk-go/aws

Create unit testing that doesn't need a running instance of Mongo to function.

Originally posted by @MrAlias in #26

See the original comment:
https://github.com/open-telemetry/opentelemetry-go-contrib/pull/20/files#r419518073

This could be addressed with upstream changes to expose route information, but for now the plugin will generate span names with high cardinality.

It seems that there is no instrumentation library for gqlgen for now.

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

Reference: https://github.com/rot1024/otelgqlgen (Created for experimental)

https://github.com/olivere/elastic

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/DataDog/dd-trace-go/tree/v1/contrib/olivere/elastic

https://github.com/graph-gophers/graphql-go

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/DataDog/dd-trace-go/tree/v1/contrib/graph-gophers/graphql-go

I was thinking how the plugins should be laid out. At first I was stripping the code hosting name, so I had go.opentelemetry.io/contrib/plugins/gorilla/mux. But I think that maybe it should just repeat the import path of the instrumented library, so basically ``go.opentelemetry.io/contrib/plugins/<IMPORT_PATH>`, like:

• go.opentelemetry.io/contrib/plugins/github.com/gorilla/mux
• go.opentelemetry.io/contrib/plugins/gopkg.in/macaron.v1
• go.opentelemetry.io/contrib/plugins/database/sql

The mock tracer in internal/trace is a modified copy of the mock tracer in otel-go. When we decide that our copy of mock tracer meets the needs of the instrumentation testing code (so the mock tracer stabilized) then it would be good to reduce the code duplication and bring the changes back to otel-go.

It should be go.opentelemetry.io/contrib, I think. With that set up, we will need to change go.mod files in the repo to replace github.com/open-telemetry/opentelemetry-go-contrib part to the vanity URL.

https://github.com/gorilla/mux

This is done when:

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• plugin added to the opentelemetry registry -open-telemetry/opentelemetry.io#187

Hi, trying to use the gorilla mux trace middleware and I'm having this issue

$ go get go.opentelemetry.io/contrib
go: go.opentelemetry.io/[email protected]: invalid version: unknown revision 000000000000

Is this something on my side?

As per discussion with @MrAlias, we agreed that the readme in the instrumentation directory should be updated to include links to integrations that are not in the opentelemetry-go-contrib repo.

@TigerHe7 and I found that go-redis/go already contains an integration for opentelemetry.

This issue is to update the readme with a table including a link to that repo.

https://github.com/astaxie/beego

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/opentracing-contrib/beego

In both the mongo and cassandra instrumentation the testing requires and actual database:

• opentelemetry-go-contrib/instrumentation/go.mongodb.org/mongo-driver/mongo_test.go

  Lines 33 to 40 in 2baa898

  	func TestMain(m *testing.M) {
  	_, ok := os.LookupEnv("INTEGRATION")
  	if !ok {
  	fmt.Println("--- SKIP: to enable integration test, set the INTEGRATION environment variable")
  	os.Exit(0)
  	}
  	os.Exit(m.Run())
  	}

• #137 (comment)

Our current CI system does not stand any of these up so the testing is currently disabled. We should automate some form of testing to work with the CI system that supports these tests.

Instrumentation needs to be lightweight when used. It should not have any large dependencies. However, there are multiple instrumentation packages that import the go.opentelemetry.io/otel/sdk package. Most common this is in examples or tests.

This dependency needs to be removed. It will likely depend on the resolution of open-telemetry/opentelemetry-go#872.

What's the proper way to leverage this code in external projects? Go seems to be choking up on the contrib/replace syntax used in most of the modules files

Example:

go get -u go.opentelemetry.io/contrib/plugins/labstack/echo 
go: downloading go.opentelemetry.io/contrib v0.0.0-20200526151459-f2c18b305db9
go: downloading go.opentelemetry.io/contrib/plugins/labstack/echo v0.0.0-20200526151459-f2c18b305db9
go: go.opentelemetry.io/contrib/plugins/labstack/echo upgrade => v0.0.0-20200526151459-f2c18b305db9
go get: go.opentelemetry.io/contrib/plugins/labstack/[email protected] requires
        go.opentelemetry.io/[email protected]: invalid version: unknown revision 000000000000

I also tried a simple go get -u go get -u go.opentelemetry.io/contrib but it discovers the go.mod in plugins/labstack/echo and bombs out with the error from above

Any help would be appreciated - thanks!

https://github.com/gin-gonic/gin

This is done when:

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• plugin added to the opentelemetry registry - open-telemetry/opentelemetry.io#188

https://gopkg.in/confluentinc/confluent-kafka-go.v1/kafka

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/DataDog/dd-trace-go/tree/v1/contrib/confluentinc/confluent-kafka-go/kafka

Similar to the open tracing support https://github.com/opentracing-contrib/go-stdlib

https://github.com/mongodb/mongo-go-driver

This is done when:

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• plugin added to the opentelemetry registry

https://github.com/Shopify/sarama

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/DataDog/dd-trace-go/tree/v1/contrib/Shopify/sarama

This PR could be used to continue working on a Gormtrace plugin.
#2

Per this comment this repo needs an automated release tagging script similar to that used for https://github.com/open-telemetry/opentelemetry-go. Providing this will help to address #45 (the work still needs to be done to perform the actual release).

In addition, as mentioned here we also need a way to bump the version of go.opentelemetry.io/otel whenever a release is made in the main repo - and fix any API breakage in these contributed plugins.

https://github.com/gocql/gocql

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

• https://github.com/DataDog/dd-trace-go/tree/v1/contrib/gocql/gocql

We (@alolita, @ercl, @connorlindsey) are interested in developing a push-based exporter, sending metrics data to a Cortex instance for supporting scalable metrics storage and processing.

We plan to provide a detailed design document for review, code and tests to support this implementation. Please assign this issue to us for implementation. You can assign it to @alolita since we’re still in the process of becoming members.

We also request a mentor from the Go SDK maintainer team for this project for design and code review and guidance.

Filed by: @connorlindsey
Assigned to: @alolita

https://github.com/googleapis/google-cloud-go

Initial packages to target:

• bigquery
• bigtable
• firestore
• pubsub
• spanner
• storage

Tasks

• code complete with tests passing
• Dockerfile with example app showing instrumentation
• documentation updated
• instrumentation added to the opentelemetry registry

Prior Art

OpenCensus documented support, but it looks more like instructions on how to start spans: https://opencensus.io/integrations/google_cloud/

Maybe we can do better(?)

OpenTelemetry should detect GKE openCensus resources and send them to the desired collector/exporter.

OC has a resource mapping. We should consider the same feature for OT.

See OpenCensus https://godoc.org/go.opencensus.io/plugin/ocgrpc

Much easier to use and implement, now:

s := grpc.NewServer(
		grpc.UnaryInterceptor(grpctrace.UnaryServerInterceptor(global.Tracer(""))),
		grpc.StreamInterceptor(grpctrace.StreamServerInterceptor(global.Tracer(""))),
	)

After:

s := grpc.NewServer(grpc.StatsHandler(&grpctrace.NewServerHandler(global.Tracer(""))))