Update Tracer API with instrumentation version (#802)

* Update Tracer API with instrumentation version

Add option to the `Provider.Tracer` method to specify the
instrumentation version.

Update the global, noop, opentracing bridge, and default SDK
implementations.

This does not propagate the instrumentation library version to the
exported span. That is left for a follow-on PR.

* Revert trace_test.go

This is for the next PR.

* Update SDK to include version for default instrumentation

If the instrumentation library name is empty and the default
instrumentation is uses, include the SDK version.

* Update comments and documentation

* Remove default instrumentation version

api/global/internal/trace.go

@@ -75,7 +75,7 @@ func (p *traceProvider) setDelegate(provider trace.Provider) {
 }
 
 // Tracer implements trace.Provider.
-func (p *traceProvider) Tracer(name string) trace.Tracer {
+func (p *traceProvider) Tracer(name string, opts ...trace.TracerOption) trace.Tracer {
 	p.mtx.Lock()
 	defer p.mtx.Unlock()
 
@@ -83,7 +83,7 @@ func (p *traceProvider) Tracer(name string) trace.Tracer {
 		return p.delegate.Tracer(name)
 	}
 
-	t := &tracer{name: name}
+	t := &tracer{name: name, opts: opts}
 	p.tracers = append(p.tracers, t)
 	return t
 }
@@ -95,6 +95,7 @@ func (p *traceProvider) Tracer(name string) trace.Tracer {
 type tracer struct {
 	once sync.Once
 	name string
+	opts []trace.TracerOption
 
 	delegate trace.Tracer
 }
@@ -110,7 +111,7 @@ var _ trace.Tracer = &tracer{}
 // Delegation only happens on the first call to this method. All subsequent
 // calls result in no delegation changes.
 func (t *tracer) setDelegate(provider trace.Provider) {
-	t.once.Do(func() { t.delegate = provider.Tracer(t.name) })
+	t.once.Do(func() { t.delegate = provider.Tracer(t.name, t.opts...) })
 }
 
 // WithSpan implements trace.Tracer by forwarding the call to t.delegate if

api/global/trace_test.go

@@ -25,7 +25,7 @@ type testTraceProvider struct{}
 
 var _ trace.Provider = &testTraceProvider{}
 
-func (*testTraceProvider) Tracer(_ string) trace.Tracer {
+func (*testTraceProvider) Tracer(_ string, _ ...trace.TracerOption) trace.Tracer {
 	return &trace.NoopTracer{}
 }
 

api/trace/api.go

@@ -24,9 +24,31 @@ import (
 )
 
 type Provider interface {
-	// Tracer creates a named tracer that implements Tracer interface.
-	// If the name is an empty string then provider uses default name.
-	Tracer(name string) Tracer
+	// Tracer creates an implementation of the Tracer interface.
+	// The instrumentationName must be the name of the library providing
+	// instrumentation. This name may be the same as the instrumented code
+	// only if that code provides built-in instrumentation. If the
+	// instrumentationName is empty, then a implementation defined default
+	// name will be used instead.
+	Tracer(instrumentationName string, opts ...TracerOption) Tracer
+}
+
+// TODO (MrAlias): unify this API option design:
+// https://github.com/open-telemetry/opentelemetry-go/issues/536
+
+// TracerConfig contains options for a Tracer.
+type TracerConfig struct {
+	InstrumentationVersion string
+}
+
+// TracerOption configures a TracerConfig option.
+type TracerOption func(*TracerConfig)
+
+// WithInstrumentationVersion sets the instrumentation version for a Tracer.
+func WithInstrumentationVersion(version string) TracerOption {
+	return func(c *TracerConfig) {
+		c.InstrumentationVersion = version
+	}
 }
 
 type Tracer interface {

api/trace/noop_trace_provider.go

@@ -19,6 +19,6 @@ type NoopProvider struct{}
 var _ Provider = NoopProvider{}
 
 // Tracer returns noop implementation of Tracer.
-func (p NoopProvider) Tracer(name string) Tracer {
+func (p NoopProvider) Tracer(_ string, _ ...TracerOption) Tracer {
 	return NoopTracer{}
 }

bridge/opentracing/wrapper.go

@@ -29,7 +29,7 @@ type WrapperProvider struct {
 var _ oteltrace.Provider = (*WrapperProvider)(nil)
 
 // Tracer returns the WrapperTracer associated with the WrapperProvider.
-func (p *WrapperProvider) Tracer(name string) oteltrace.Tracer {
+func (p *WrapperProvider) Tracer(_ string, _ ...oteltrace.TracerOption) oteltrace.Tracer {
 	return p.wTracer
 }
 

sdk/instrumentation/library.go

@@ -0,0 +1,31 @@
+// 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 instrumentation provides an instrumentation library structure to be
+passed to both the OpenTelemetry Tracer and Meter components.
+
+For more information see
+[this](https://github.com/open-telemetry/oteps/blob/master/text/0083-component.md).
+*/
+package instrumentation
+
+// Library represents the instrumentation library.
+type Library struct {
+	// Name is the name of the instrumentation library. This should be the
+	// Go package name of that library.
+	Name string
+	// Version is the version of the instrumentation library.
+	Version string
+}

sdk/trace/provider.go

@@ -19,6 +19,7 @@ import (
 	"sync/atomic"
 
 	export "go.opentelemetry.io/otel/sdk/export/trace"
+	"go.opentelemetry.io/otel/sdk/instrumentation"
 	"go.opentelemetry.io/otel/sdk/resource"
 
 	apitrace "go.opentelemetry.io/otel/api/trace"
@@ -45,7 +46,7 @@ type ProviderOption func(*ProviderOptions)
 
 type Provider struct {
 	mu             sync.Mutex
-	namedTracer    map[string]*tracer
+	namedTracer    map[instrumentation.Library]*tracer
 	spanProcessors atomic.Value
 	config         atomic.Value // access atomically
 }
@@ -63,7 +64,7 @@ func NewProvider(opts ...ProviderOption) (*Provider, error) {
 	}
 
 	tp := &Provider{
-		namedTracer: make(map[string]*tracer),
+		namedTracer: make(map[instrumentation.Library]*tracer),
 	}
 	tp.config.Store(&Config{
 		DefaultSampler:       AlwaysSample(),
@@ -93,16 +94,27 @@ func NewProvider(opts ...ProviderOption) (*Provider, error) {
 
 // Tracer with the given name. If a tracer for the given name does not exist,
 // it is created first. If the name is empty, DefaultTracerName is used.
-func (p *Provider) Tracer(name string) apitrace.Tracer {
+func (p *Provider) Tracer(name string, opts ...apitrace.TracerOption) apitrace.Tracer {
+	c := new(apitrace.TracerConfig)
+	for _, o := range opts {
+		o(c)
+	}
 	p.mu.Lock()
 	defer p.mu.Unlock()
 	if name == "" {
 		name = defaultTracerName
 	}
-	t, ok := p.namedTracer[name]
+	il := instrumentation.Library{
+		Name:    name,
+		Version: c.InstrumentationVersion,
+	}
+	t, ok := p.namedTracer[il]
 	if !ok {
-		t = &tracer{name: name, provider: p}
-		p.namedTracer[name] = t
+		t = &tracer{
+			provider:               p,
+			instrumentationLibrary: il,
+		}
+		p.namedTracer[il] = t
 	}
 	return t
 }

sdk/trace/tracer.go

@@ -19,11 +19,12 @@ import (
 
 	apitrace "go.opentelemetry.io/otel/api/trace"
 	"go.opentelemetry.io/otel/internal/trace/parent"
+	"go.opentelemetry.io/otel/sdk/instrumentation"
 )
 
 type tracer struct {
-	provider *Provider
-	name     string
+	provider               *Provider
+	instrumentationLibrary instrumentation.Library
 }
 
 var _ apitrace.Tracer = &tracer{}