Deprecate Library and move all uses to Scope

CHANGELOG.md

@@ -17,6 +17,11 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Support for go1.16. Support is now only for go1.17 and go1.18 (#2917)
 
+### Deprecated
+
+- The `Library` struct in the `go.opentelemetry.io/otel/sdk/instrumentation` package is deprecated.
+  Use the equivalent `Scope` struct instead. (#2977)
+
 ## [1.7.0/0.30.0] - 2022-04-28
 
 ### Added

bridge/opencensus/exporter.go

@@ -64,8 +64,8 @@ type censusLibraryReader struct {
 	metrics []*metricdata.Metric
 }
 
-func (r censusLibraryReader) ForEach(readerFunc func(instrumentation.Library, export.Reader) error) error {
-	return readerFunc(instrumentation.Library{
+func (r censusLibraryReader) ForEach(readerFunc func(instrumentation.Scope, export.Reader) error) error {
+	return readerFunc(instrumentation.Scope{
 		Name: "OpenCensus Bridge",
 	}, &metricReader{metrics: r.metrics})
 }

bridge/opencensus/exporter_test.go

@@ -47,7 +47,7 @@ type fakeExporter struct {
 
 func (f *fakeExporter) Export(ctx context.Context, res *resource.Resource, ilr export.InstrumentationLibraryReader) error {
 	return controllertest.ReadAll(ilr, aggregation.StatelessTemporalitySelector(),
-		func(_ instrumentation.Library, record export.Record) error {
+		func(_ instrumentation.Scope, record export.Record) error {
 			f.resource = res
 			f.records = append(f.records, record)
 			return f.err

exporters/jaeger/jaeger_benchmark_test.go

@@ -61,7 +61,7 @@ func spans(n int) []tracesdk.ReadOnlySpan {
 			StartTime:   now,
 			EndTime:     now,
 			SpanKind:    trace.SpanKindClient,
-			InstrumentationLibrary: instrumentation.Library{
+			InstrumentationLibrary: instrumentation.Scope{
 				Name: instrLibName,
 			},
 		}

exporters/jaeger/jaeger_test.go

@@ -187,7 +187,7 @@ func TestSpanSnapshotToThrift(t *testing.T) {
 				EndTime:   now,
 				Status:    sdktrace.Status{Code: codes.Error},
 				SpanKind:  trace.SpanKindClient,
-				InstrumentationLibrary: instrumentation.Library{
+				InstrumentationLibrary: instrumentation.Scope{
 					Name:    instrLibName,
 					Version: instrLibVersion,
 				},
@@ -245,7 +245,7 @@ func TestSpanSnapshotToThrift(t *testing.T) {
 					Description: statusMessage,
 				},
 				SpanKind: trace.SpanKindClient,
-				InstrumentationLibrary: instrumentation.Library{
+				InstrumentationLibrary: instrumentation.Scope{
 					Name:    instrLibName,
 					Version: instrLibVersion,
 				},
@@ -330,7 +330,7 @@ func TestSpanSnapshotToThrift(t *testing.T) {
 					Description: statusMessage,
 				},
 				SpanKind: trace.SpanKindInternal,
-				InstrumentationLibrary: instrumentation.Library{
+				InstrumentationLibrary: instrumentation.Scope{
 					Name:    instrLibName,
 					Version: instrLibVersion,
 				},
@@ -383,7 +383,7 @@ func TestSpanSnapshotToThrift(t *testing.T) {
 					Description: statusMessage,
 				},
 				SpanKind: trace.SpanKindInternal,
-				InstrumentationLibrary: instrumentation.Library{
+				InstrumentationLibrary: instrumentation.Scope{
 					Name:    instrLibName,
 					Version: instrLibVersion,
 				},

exporters/otlp/otlpmetric/exporter_test.go

@@ -728,7 +728,7 @@ func TestStatelessAggregationTemporality(t *testing.T) {
 func runMetricExportTests(t *testing.T, opts []otlpmetric.Option, res *resource.Resource, records []testRecord, expected []*metricpb.ResourceMetrics) {
 	exp, driver := newExporter(t, opts...)
 
-	libraryRecs := map[instrumentation.Library][]export.Record{}
+	libraryRecs := map[instrumentation.Scope][]export.Record{}
 	for _, r := range records {
 		lcopy := make([]attribute.KeyValue, len(r.attrs))
 		copy(lcopy, r.attrs)
@@ -771,7 +771,7 @@ func runMetricExportTests(t *testing.T, opts []otlpmetric.Option, res *resource.
 		require.NoError(t, agg.SynchronizedMove(ckpt, &desc))
 
 		meterCfg := metric.NewMeterConfig(r.meterOpts...)
-		lib := instrumentation.Library{
+		lib := instrumentation.Scope{
 			Name:      r.meterName,
 			Version:   meterCfg.InstrumentationVersion(),
 			SchemaURL: meterCfg.SchemaURL(),
@@ -838,7 +838,7 @@ func TestEmptyMetricExport(t *testing.T) {
 		},
 	} {
 		driver.Reset()
-		require.NoError(t, exp.Export(context.Background(), resource.Empty(), processortest.MultiInstrumentationLibraryReader(map[instrumentation.Library][]export.Record{
+		require.NoError(t, exp.Export(context.Background(), resource.Empty(), processortest.MultiInstrumentationLibraryReader(map[instrumentation.Scope][]export.Record{
 			{
 				Name: testLibName,
 			}: test.records,

exporters/otlp/otlpmetric/internal/metrictransform/metric.go

@@ -74,7 +74,7 @@ func toNanos(t time.Time) uint64 {
 func InstrumentationLibraryReader(ctx context.Context, temporalitySelector aggregation.TemporalitySelector, res *resource.Resource, ilmr export.InstrumentationLibraryReader, numWorkers uint) (*metricpb.ResourceMetrics, error) {
 	var sms []*metricpb.ScopeMetrics
 
-	err := ilmr.ForEach(func(lib instrumentation.Library, mr export.Reader) error {
+	err := ilmr.ForEach(func(lib instrumentation.Scope, mr export.Reader) error {
 		records, errc := source(ctx, temporalitySelector, mr)
 
 		// Start a fixed number of goroutines to transform records.

exporters/otlp/otlpmetric/internal/otlpmetrictest/data.go

@@ -48,7 +48,7 @@ func OneRecordReader() export.InstrumentationLibraryReader {
 	rec := export.NewRecord(&desc, &attrs, agg[0].Aggregation(), start, end)
 
 	return processortest.MultiInstrumentationLibraryReader(
-		map[instrumentation.Library][]export.Record{
+		map[instrumentation.Scope][]export.Record{
 			{
 				Name: "onelib",
 			}: {rec},
@@ -66,6 +66,6 @@ type FailReader struct{}
 var _ export.InstrumentationLibraryReader = FailReader{}
 
 // ForEach implements export.Reader. It always fails.
-func (FailReader) ForEach(readerFunc func(instrumentation.Library, export.Reader) error) error {
+func (FailReader) ForEach(readerFunc func(instrumentation.Scope, export.Reader) error) error {
 	return fmt.Errorf("fail")
 }

exporters/otlp/otlptrace/internal/otlptracetest/data.go

@@ -54,7 +54,7 @@ func SingleReadOnlySpan() []tracesdk.ReadOnlySpan {
 			DroppedLinks:      0,
 			ChildSpanCount:    0,
 			Resource:          resource.NewSchemaless(attribute.String("a", "b")),
-			InstrumentationLibrary: instrumentation.Library{
+			InstrumentationLibrary: instrumentation.Scope{
 				Name:    "bar",
 				Version: "0.0.0",
 			},

exporters/otlp/otlptrace/internal/tracetransform/instrumentation.go

@@ -19,8 +19,8 @@ import (
 	commonpb "go.opentelemetry.io/proto/otlp/common/v1"
 )
 
-func InstrumentationScope(il instrumentation.Library) *commonpb.InstrumentationScope {
-	if il == (instrumentation.Library{}) {
+func InstrumentationScope(il instrumentation.Scope) *commonpb.InstrumentationScope {
+	if il == (instrumentation.Scope{}) {
 		return nil
 	}
 	return &commonpb.InstrumentationScope{

exporters/otlp/otlptrace/internal/tracetransform/span.go

@@ -34,7 +34,7 @@ func Spans(sdl []tracesdk.ReadOnlySpan) []*tracepb.ResourceSpans {
 
 	type key struct {
 		r  attribute.Distinct
-		il instrumentation.Library
+		il instrumentation.Scope
 	}
 	ssm := make(map[key]*tracepb.ScopeSpans)
 

exporters/otlp/otlptrace/internal/tracetransform/span_test.go

@@ -264,7 +264,7 @@ func TestSpanData(t *testing.T) {
 			attribute.Int64("rk2", 5),
 			attribute.StringSlice("rk3", []string{"sv1", "sv2"}),
 		),
-		InstrumentationLibrary: instrumentation.Library{
+		InstrumentationLibrary: instrumentation.Scope{
 			Name:      "go.opentelemetry.io/test/otel",
 			Version:   "v0.0.1",
 			SchemaURL: semconv.SchemaURL,

exporters/prometheus/prometheus.go

@@ -151,7 +151,7 @@ func (c *collector) Describe(ch chan<- *prometheus.Desc) {
 	c.exp.lock.RLock()
 	defer c.exp.lock.RUnlock()
 
-	_ = c.exp.Controller().ForEach(func(_ instrumentation.Library, reader export.Reader) error {
+	_ = c.exp.Controller().ForEach(func(_ instrumentation.Scope, reader export.Reader) error {
 		return reader.ForEach(c.exp, func(record export.Record) error {
 			var attrKeys []string
 			mergeAttrs(record, c.exp.controller.Resource(), &attrKeys, nil)
@@ -174,7 +174,7 @@ func (c *collector) Collect(ch chan<- prometheus.Metric) {
 		otel.Handle(err)
 	}
 
-	err := ctrl.ForEach(func(_ instrumentation.Library, reader export.Reader) error {
+	err := ctrl.ForEach(func(_ instrumentation.Scope, reader export.Reader) error {
 		return reader.ForEach(c.exp, func(record export.Record) error {
 			agg := record.Aggregation()
 			numberKind := record.Descriptor().NumberKind()

exporters/stdout/stdoutmetric/metric.go

@@ -52,7 +52,7 @@ func (e *metricExporter) TemporalityFor(desc *sdkapi.Descriptor, kind aggregatio
 func (e *metricExporter) Export(_ context.Context, res *resource.Resource, reader export.InstrumentationLibraryReader) error {
 	var aggError error
 	var batch []line
-	aggError = reader.ForEach(func(lib instrumentation.Library, mr export.Reader) error {
+	aggError = reader.ForEach(func(lib instrumentation.Scope, mr export.Reader) error {
 		var instAttrs []attribute.KeyValue
 		if name := lib.Name; name != "" {
 			instAttrs = append(instAttrs, attribute.String("instrumentation.name", name))

exporters/zipkin/model_test.go

@@ -829,15 +829,15 @@ func TestTagsTransformation(t *testing.T) {
 		{
 			name: "instrLib-empty",
 			data: tracetest.SpanStub{
-				InstrumentationLibrary: instrumentation.Library{},
+				InstrumentationLibrary: instrumentation.Scope{},
 			},
 			want: nil,
 		},
 		{
 			name: "instrLib-noversion",
 			data: tracetest.SpanStub{
 				Attributes: []attribute.KeyValue{},
-				InstrumentationLibrary: instrumentation.Library{
+				InstrumentationLibrary: instrumentation.Scope{
 					Name: instrLibName,
 				},
 			},
@@ -849,7 +849,7 @@ func TestTagsTransformation(t *testing.T) {
 			name: "instrLib-with-version",
 			data: tracetest.SpanStub{
 				Attributes: []attribute.KeyValue{},
-				InstrumentationLibrary: instrumentation.Library{
+				InstrumentationLibrary: instrumentation.Scope{
 					Name:    instrLibName,
 					Version: instrLibVersion,
 				},

sdk/instrumentation/library.go

@@ -22,4 +22,5 @@ For more information see
 package instrumentation // import "go.opentelemetry.io/otel/sdk/instrumentation"
 
 // Library represents the instrumentation library.
+// Deprecated: please use Scope instead.
 type Library = Scope

sdk/metric/controller/basic/controller.go

@@ -85,7 +85,7 @@ var _ metric.MeterProvider = &Controller{}
 // with opts.
 func (c *Controller) Meter(instrumentationName string, opts ...metric.MeterOption) metric.Meter {
 	cfg := metric.NewMeterConfig(opts...)
-	library := instrumentation.Library{
+	library := instrumentation.Scope{
 		Name:      instrumentationName,
 		Version:   cfg.InstrumentationVersion(),
 		SchemaURL: cfg.SchemaURL(),
@@ -108,7 +108,7 @@ func (c *Controller) Meter(instrumentationName string, opts ...metric.MeterOptio
 type accumulatorCheckpointer struct {
 	*sdk.Accumulator
 	checkpointer export.Checkpointer
-	library      instrumentation.Library
+	library      instrumentation.Scope
 }
 
 var _ sdkapi.MeterImpl = &accumulatorCheckpointer{}
@@ -323,7 +323,7 @@ func (c *Controller) export(ctx context.Context) error { // nolint:revive  // me
 }
 
 // ForEach implements export.InstrumentationLibraryReader.
-func (c *Controller) ForEach(readerFunc func(l instrumentation.Library, r export.Reader) error) error {
+func (c *Controller) ForEach(readerFunc func(l instrumentation.Scope, r export.Reader) error) error {
 	for _, acPair := range c.accumulatorList() {
 		reader := acPair.checkpointer.Reader()
 		// TODO: We should not fail fast; instead accumulate errors.

sdk/metric/controller/basic/controller_test.go

@@ -43,7 +43,7 @@ func getMap(t *testing.T, cont *controller.Controller) map[string]float64 {
 	out := processortest.NewOutput(attribute.DefaultEncoder())
 
 	require.NoError(t, cont.ForEach(
-		func(_ instrumentation.Library, reader export.Reader) error {
+		func(_ instrumentation.Scope, reader export.Reader) error {
 			return reader.ForEach(
 				aggregation.CumulativeTemporalitySelector(),
 				func(record export.Record) error {

sdk/metric/controller/controllertest/test.go

@@ -75,9 +75,9 @@ func (t MockTicker) C() <-chan time.Time {
 func ReadAll(
 	reader export.InstrumentationLibraryReader,
 	kind aggregation.TemporalitySelector,
-	apply func(instrumentation.Library, export.Record) error,
+	apply func(instrumentation.Scope, export.Record) error,
 ) error {
-	return reader.ForEach(func(library instrumentation.Library, reader export.Reader) error {
+	return reader.ForEach(func(library instrumentation.Scope, reader export.Reader) error {
 		return reader.ForEach(kind, func(record export.Record) error {
 			return apply(library, record)
 		})

sdk/metric/export/metric.go

@@ -155,7 +155,7 @@ type InstrumentationLibraryReader interface {
 	// ForEach calls the passed function once per instrumentation library,
 	// allowing the caller to emit metrics grouped by the library that
 	// produced them.
-	ForEach(readerFunc func(instrumentation.Library, Reader) error) error
+	ForEach(readerFunc func(instrumentation.Scope, Reader) error) error
 }
 
 // Reader allows a controller to access a complete checkpoint of

sdk/metric/metrictest/exporter.go

@@ -64,9 +64,12 @@ func NewTestMeterProvider(opts ...Option) (metric.MeterProvider, *Exporter) {
 	return c, exp
 }
 
-// Library is the same as "sdk/instrumentation".Library but there is
+// Deprecated: please use Scope instead.
+type Library = Scope
+
+// Scope is the same as "sdk/instrumentation".Scope but there is
 // a package cycle to use it so it is redeclared here.
-type Library struct {
+type Scope struct {
 	InstrumentationName    string
 	InstrumentationVersion string
 	SchemaURL              string
@@ -75,7 +78,7 @@ type Library struct {
 // ExportRecord represents one collected datapoint from the Exporter.
 type ExportRecord struct {
 	InstrumentName         string
-	InstrumentationLibrary Library
+	InstrumentationLibrary Scope
 	Attributes             []attribute.KeyValue
 	AggregationKind        aggregation.Kind
 	NumberKind             number.Kind
@@ -95,8 +98,8 @@ func (e *Exporter) Collect(ctx context.Context) error {
 		return err
 	}
 
-	return e.controller.ForEach(func(l instrumentation.Library, r export.Reader) error {
-		lib := Library{
+	return e.controller.ForEach(func(l instrumentation.Scope, r export.Reader) error {
+		lib := Scope{
 			InstrumentationName:    l.Name,
 			InstrumentationVersion: l.Version,
 			SchemaURL:              l.SchemaURL,

sdk/metric/processor/basic/basic_test.go

@@ -471,7 +471,7 @@ func TestCounterObserverEndToEnd(t *testing.T) {
 
 		exporter := processortest.New(eselector, attribute.DefaultEncoder())
 		require.NoError(t, exporter.Export(ctx, resource.Empty(), processortest.OneInstrumentationLibraryReader(
-			instrumentation.Library{
+			instrumentation.Scope{
 				Name: "test",
 			}, reader)))
 

sdk/metric/processor/processortest/test.go

@@ -243,7 +243,7 @@ func (o *Output) AddRecord(rec export.Record) error {
 }
 
 // AddRecordWithResource merges rec into this Output.
-func (o *Output) AddInstrumentationLibraryRecord(_ instrumentation.Library, rec export.Record) error {
+func (o *Output) AddInstrumentationLibraryRecord(_ instrumentation.Scope, rec export.Record) error {
 	return o.AddRecordWithResource(rec, resource.Empty())
 }
 
@@ -340,7 +340,7 @@ func (e *Exporter) Export(_ context.Context, res *resource.Resource, ckpt export
 	e.output.Lock()
 	defer e.output.Unlock()
 	e.exportCount++
-	return ckpt.ForEach(func(library instrumentation.Library, mr export.Reader) error {
+	return ckpt.ForEach(func(library instrumentation.Scope, mr export.Reader) error {
 		return mr.ForEach(e.TemporalitySelector, func(r export.Record) error {
 			if e.InjectErr != nil {
 				if err := e.InjectErr(r); err != nil {
@@ -381,32 +381,32 @@ func (e *Exporter) Reset() {
 
 // OneInstrumentationLibraryReader returns an InstrumentationLibraryReader for
 // a single instrumentation library.
-func OneInstrumentationLibraryReader(l instrumentation.Library, r export.Reader) export.InstrumentationLibraryReader {
+func OneInstrumentationLibraryReader(l instrumentation.Scope, r export.Reader) export.InstrumentationLibraryReader {
 	return oneLibraryReader{l, r}
 }
 
 type oneLibraryReader struct {
-	library instrumentation.Library
+	library instrumentation.Scope
 	reader  export.Reader
 }
 
-func (o oneLibraryReader) ForEach(readerFunc func(instrumentation.Library, export.Reader) error) error {
+func (o oneLibraryReader) ForEach(readerFunc func(instrumentation.Scope, export.Reader) error) error {
 	return readerFunc(o.library, o.reader)
 }
 
 // MultiInstrumentationLibraryReader returns an InstrumentationLibraryReader
 // for a group of records that came from multiple instrumentation libraries.
-func MultiInstrumentationLibraryReader(records map[instrumentation.Library][]export.Record) export.InstrumentationLibraryReader {
+func MultiInstrumentationLibraryReader(records map[instrumentation.Scope][]export.Record) export.InstrumentationLibraryReader {
 	return instrumentationLibraryReader{records: records}
 }
 
 type instrumentationLibraryReader struct {
-	records map[instrumentation.Library][]export.Record
+	records map[instrumentation.Scope][]export.Record
 }
 
 var _ export.InstrumentationLibraryReader = instrumentationLibraryReader{}
 
-func (m instrumentationLibraryReader) ForEach(fn func(instrumentation.Library, export.Reader) error) error {
+func (m instrumentationLibraryReader) ForEach(fn func(instrumentation.Scope, export.Reader) error) error {
 	for library, records := range m.records {
 		if err := fn(library, &metricReader{records: records}); err != nil {
 			return err

sdk/metric/processor/processortest/test_test.go

@@ -80,7 +80,7 @@ func TestProcessorTesting(t *testing.T) {
 	)
 
 	err := exporter.Export(context.Background(), res, processortest.OneInstrumentationLibraryReader(
-		instrumentation.Library{
+		instrumentation.Scope{
 			Name: "test",
 		},
 		checkpointer.Reader(),