Merge main into new_sdk/main (#3141)

* Use already enabled revive linter and add depguard (#2883) * Refactor golangci-lint conf Order settings alphabetically. * Add revive settings to golangci conf * Check blank imports * Check bool-literal-in-expr * Check constant-logical-expr * Check context-as-argument * Check context-key-type * Check deep-exit * Check defer * Check dot-imports * Check duplicated-imports * Check early-return * Check empty-block * Check empty-lines * Check error-naming * Check error-return * Check error-strings * Check errorf * Stop ignoring context first arg in tests * Check exported comments * Check flag-parameter * Check identical branches * Check if-return * Check increment-decrement * Check indent-error-flow * Check deny list of go imports * Check import shadowing * Check package comments * Check range * Check range val in closure * Check range val address * Check redefines builtin id * Check string-format * Check struct tag * Check superfluous else * Check time equal * Check var naming * Check var declaration * Check unconditional recursion * Check unexported return * Check unhandled errors * Check unnecessary stmt * Check unnecessary break * Check waitgroup by value * Exclude deep-exit check in example*_test.go files * Move the minimum version to go 1.17 (#2917) * Move the minimum version to go 1.17 * Update readme and changelog Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com> * Use ByteSliceToString from golang.org/x/sys/unix (#2924) Use unix.ByteSliceToString to convert Utsname []byte fields to strings. This also allows to drop the charsToString helper which serves the same purpose and matches ByteSliceToString's implementation. Signed-off-by: Tobias Klauser <tklauser@distanz.ch> Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * docs: fix typo (#2935) * add timeout to grpc connection in otel-collector example (#2939) * Closes: #2951 (#2952) This PR updates the example listed in the getting started doc so that it will compile without error. It also makes this example consistent with the code found in https://github.com/open-telemetry/opentelemetry-go/blob/main/example/fib/main.go Signed-off-by: Brad Topol <btopol@us.ibm.com> * fix data-model link (#2955) * Bump go.opentelemetry.io/proto/otlp from v0.16.0 to v0.18.0 (#2960) * Move to using Instrumentation Scope (#2976) * Move to using Instrumentation Scope * Use type alias, not definition * Add a changelog entry * docs(website_docs): fix exporting_data.md and getting-started.md toc (#2930) * docs(website_docs): fix toc * docs(website_docs): fix toc * update exporting_data.md for rerun check-links * update exporting_data.md for rerun check-links Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com> Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Update getting-started.md (#2984) grammar edit for line 175 of readme * fix typo (#2986) * fix typo * spell fix * typo fix (#2991) * added traces.txt to gitignore for fib (#2993) * Deprecate Library and move all uses to Scope (#2977) * Deprecate Library and move all uses to Scope * Add PR number to changelog * Don't change signatures in stable modules * Revert some changes * Rename internal struct names * A bit more renaming * Update sdk/trace/span.go Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Update based on feedback * Revert change Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> * Feat/bridge support text map (#2911) * feat: support TextMap * doc: add comment * test: support for ot.TextMap * Retrieve lost code due to merge * fix: retrieve lost code due to merge. test: support for ot.HTTPHeaders * go mod tidy * Optimized code style, add changelog * doc: Restore comments * wip: add test cases * test: fix args error * delete empty line * Fix syntax and changelog errors * Fix formatting errors Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com> Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> * Add a release template (#2863) * Add a release template * Update the about field Co-authored-by: Damien Mathieu <42@dmathieu.com> * Fix linting Issues * Add ignore for template link Co-authored-by: Damien Mathieu <42@dmathieu.com> Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com> Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> * Add workflow to automate bundling dependabot PRs (#2997) Signed-off-by: Anthony J Mirabella <a9@aneurysm9.com> * Release prep 1.8.0 (#3001) * Update CHANGELOG and versions.yaml for 1.8.0 release Signed-off-by: Anthony J Mirabella <a9@aneurysm9.com> * Update go-build-tools Signed-off-by: Anthony J Mirabella <a9@aneurysm9.com> * Prepare stable-v1 for version v1.8.0 * Prepare experimental-metrics for version v0.31.0 * Prepare bridge for version v0.31.0 * `make go-mod-tidy` should use `-compat=1.17` now Signed-off-by: Anthony J Mirabella <a9@aneurysm9.com> * Update CHANGELOG.md Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Add benchmark metric test for UpDownCounter (#2655) * add benchmark metric test for UpDownCounter * move counter annotation up * fix syncFloat64 to syncInt64 * fix syncFloat64 to syncInt64 * fix go-lint err * Add semconv/v1.11.0 (#3009) Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> * Add semconv/v1.12.0 (#3010) * Add semconv/v1.12.0 * Update all semconv use to v1.12.0 Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> * Add http.method attribute to http server metric (#3018) * Add http.method attribute to http server metric Signed-off-by: Ziqi Zhao <zhaoziqi9146@gmail.com> * fix lint Signed-off-by: Ziqi Zhao <zhaoziqi9146@gmail.com> * fix lint Signed-off-by: Ziqi Zhao <zhaoziqi9146@gmail.com> * fix for reviews Signed-off-by: Ziqi Zhao <zhaoziqi9146@gmail.com> * add changelog entry Signed-off-by: Ziqi Zhao <zhaoziqi9146@gmail.com> * Add tests and fix opentracing bridge defer warning (#3029) * add tests and fix opentracing bridge defer warning * add changelog entry * Update CHANGELOG.md Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Update bridge/opentracing/bridge_test.go Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Introduce "split" metric schema transformation (#2999) This is a new transformation type that allows to describe a change where a metric is converted to several other metrics by eliminating an attribute. An example of such change that happened recently is this: open-telemetry/opentelemetry-specification#2617 This PR implements specification change open-telemetry/opentelemetry-specification#2653 This PR creates package v1.1 for the new functionality. The old package v1.0 remains unchanged. * Release v1.9.0 (#3052) * Bump versions in versions.yaml * Prepare stable-v1 for version v1.9.0 * Prepare experimental-schema for version v0.0.3 * Update changelog for release * Replace ioutil with io and os (#3058) * Make several vars into consts (#3068) * Add support for Go 1.19 (#3077) * Add support for Go 1.19 * Update CHANGELOG.md Co-authored-by: Sam Xie <sam@samxie.me> Co-authored-by: Sam Xie <sam@samxie.me> * Update compatibility documentation (#3079) Remove 3 month timeline for backwards support of old versions of Go. * Fix `opentracing.Bridge` where it miss identifying the spanKind (#3096) * Fix opentracing.Bridge where it was not identifying the spanKinf correctly * fix test * changelog * Keeping backward comppatibillity * Update CHANGELOG.md Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> * Update CHANGELOG.md Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com> * replace `required` by `requirementlevel` (#3103) * Change the inclusivity of exponential histogram bounds (#2982) * Use lower-inclusive boundaries * make exponent and logarithm more symmetric Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> * Update golangci-lint to v1.48.0 (#3105) * Update golangci-lint to v1.48.0 Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com> * Bump go.opentelemetry.io/proto/otlp from v0.18.0 to v0.19.0 (#3107) * Bump go.opentelemetry.io/proto/otlp from v0.18.0 to v0.19.0 Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> * Update tracer to guard for a nil ctx (#3110) * Update tracer to guard for a nil ctx Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com> Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Fix sdk/instrumentation pkg docs (#3130) * Add instrumentation scope attributes (#3131) * Add WithScopeAttributes TracerOption to trace API * Add Attributes field to instrumentation Scope * Use scope attributes for new Tracer * Fix stdouttrace expected test output * Allow unexported Set fields in sdk/trace test * Export instrumentation scope attrs in OTLP * Add changes to the changelog * Fix imports with make lint * Add unit tests for WithScopeAttributes * Fix English in Scope documentation * Add WithScopeAttributes MeterOption to metric API package (#3132) * Add WithScopeAttributes MeterOption to metric pkg * Add MeterConfig unit tests * Add changes to changelog * Fix import linting * Update MeterProvider documentation Include information about how to use WithScopeAttributes. * Refactor TracerProvider documentation (#3133) * Refactor TracerProvider documentation * Fix English article * Grammar fixes * consistency-of: Changed signal names for website docs (#3137) * Shut down all processors even on error (#3091) * Fix stdoutmetric example test The merged instrumentation Scope includes SchemaURL and Attributes now, add them to the expected output. Signed-off-by: Brad Topol <btopol@us.ibm.com> Signed-off-by: Anthony J Mirabella <a9@aneurysm9.com> Signed-off-by: Ziqi Zhao <zhaoziqi9146@gmail.com> Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com> Co-authored-by: Tobias Klauser <tobias.klauser@gmail.com> Co-authored-by: petrie <244236866@qq.com> Co-authored-by: Damien Mathieu <42@dmathieu.com> Co-authored-by: Brad Topol <btopol@us.ibm.com> Co-authored-by: Craig Pastro <pastro.craig@gmail.com> Co-authored-by: Kshitija Murudi <kmurudi@ncsu.edu> Co-authored-by: Petrie Liu <lpfvip2008@gmail.com> Co-authored-by: Guangya Liu <gyliu513@gmail.com> Co-authored-by: Craig Pastro <craig.pastro@auth0.com> Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> Co-authored-by: ttoad <qq530901331@outlook.com> Co-authored-by: Ziqi Zhao <zhaoziqi9146@gmail.com> Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Co-authored-by: Håvard Anda Estensen <haavard.ae@gmail.com> Co-authored-by: Mikhail Mazurskiy <126021+ash2k@users.noreply.github.com> Co-authored-by: Sam Xie <sam@samxie.me> Co-authored-by: Alan Protasio <alanprot@gmail.com> Co-authored-by: Joshua MacDonald <jmacd@users.noreply.github.com> Co-authored-by: Mitch Usher <cull.methi@gmail.com> Co-authored-by: Gaurang Patel <mr.patelgaurang@gmail.com>
open-telemetry · Sep 6, 2022 · bdb917e · bdb917e
1 parent df133f0
commit bdb917e
Show file tree

Hide file tree

Showing 20 changed files with 416 additions and 49 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,13 +13,18 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Support Go 1.19.
   Include compatibility testing and document support. (#3077)
 - Upgrade go.opentelemetry.io/proto/otlp from v0.18.0 to v0.19.0 (#3107)
+- Add an `Attribute` field to the `Scope` type in `go.opentelemetry.io/otel/sdk/instrumentation`. (#3131)
+- Add the `WithScopeAttributes` `TracerOption` to the `go.opentelemetry.io/otel/trace` package. (#3131)
+- Add the `WithScopeAttributes` `MeterOption` to the `go.opentelemetry.io/otel/metric` package. (#3132)
 
 ### Changed
 
 - Fix misidentification of OpenTelemetry `SpanKind` in OpenTracing bridge (`go.opentelemetry.io/otel/bridge/opentracing`).  (#3096)
 - The exponential histogram mapping functions have been updated with
   exact upper-inclusive boundary support following the [corresponding
   specification change](https://github.com/open-telemetry/opentelemetry-specification/pull/2633). (#2982)
+- Attempting to start a span with a nil `context` will no longer cause a panic. (#3110)
+- Export scope attributes for all exporters provided by `go.opentelemetry.io/otel/exporters/otlp/otlptrace`. (#3131)
 
 ## [1.9.0/0.0.3] - 2022-08-01
 

diff --git a/bridge/opentracing/bridge_test.go b/bridge/opentracing/bridge_test.go
@@ -22,9 +22,11 @@ import (
 	"testing"
 
 	ot "github.com/opentracing/opentracing-go"
+	"github.com/opentracing/opentracing-go/ext"
 	"github.com/stretchr/testify/assert"
 
 	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/bridge/opentracing/internal"
 	"go.opentelemetry.io/otel/propagation"
 	"go.opentelemetry.io/otel/trace"
 )
@@ -425,3 +427,44 @@ func TestBridgeTracer_StartSpan(t *testing.T) {
 		})
 	}
 }
+
+func Test_otTagsToOTelAttributesKindAndError(t *testing.T) {
+	tracer := internal.NewMockTracer()
+	sc := &bridgeSpanContext{}
+
+	testCases := []struct {
+		name     string
+		opt      []ot.StartSpanOption
+		expected trace.SpanKind
+	}{
+		{
+			name:     "client",
+			opt:      []ot.StartSpanOption{ext.SpanKindRPCClient},
+			expected: trace.SpanKindClient,
+		},
+		{
+			name:     "server",
+			opt:      []ot.StartSpanOption{ext.RPCServerOption(sc)},
+			expected: trace.SpanKindServer,
+		},
+		{
+			name:     "client string",
+			opt:      []ot.StartSpanOption{ot.Tag{Key: "span.kind", Value: "client"}},
+			expected: trace.SpanKindClient,
+		},
+		{
+			name:     "server string",
+			opt:      []ot.StartSpanOption{ot.Tag{Key: "span.kind", Value: "server"}},
+			expected: trace.SpanKindServer,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			b, _ := NewTracerPair(tracer)
+
+			s := b.StartSpan(tc.name, tc.opt...)
+			assert.Equal(t, s.(*bridgeSpan).otelSpan.(*internal.MockSpan).SpanKind, tc.expected)
+		})
+	}
+}
diff --git a/exporters/otlp/otlptrace/internal/tracetransform/instrumentation.go b/exporters/otlp/otlptrace/internal/tracetransform/instrumentation.go
@@ -24,7 +24,8 @@ func InstrumentationScope(il instrumentation.Scope) *commonpb.InstrumentationSco
 		return nil
 	}
 	return &commonpb.InstrumentationScope{
-		Name:    il.Name,
-		Version: il.Version,
+		Name:       il.Name,
+		Version:    il.Version,
+		Attributes: Iterator(il.Attributes.Iter()),
 	}
 }
diff --git a/exporters/otlp/otlptrace/internal/tracetransform/instrumentation_test.go b/exporters/otlp/otlptrace/internal/tracetransform/instrumentation_test.go
@@ -0,0 +1,52 @@
+// 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 tracetransform // import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/internal/tracetransform"
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/sdk/instrumentation"
+	commonpb "go.opentelemetry.io/proto/otlp/common/v1"
+)
+
+func TestInstrumentationScope(t *testing.T) {
+	t.Run("Empty", func(t *testing.T) {
+		assert.Nil(t, InstrumentationScope(instrumentation.Scope{}))
+	})
+
+	t.Run("Mapping", func(t *testing.T) {
+		var (
+			name    = "instrumentation name"
+			version = "v0.1.0"
+			attr    = attribute.NewSet(attribute.String("domain", "trace"))
+			attrPb  = Iterator(attr.Iter())
+		)
+		expected := &commonpb.InstrumentationScope{
+			Name:       name,
+			Version:    version,
+			Attributes: attrPb,
+		}
+		actual := InstrumentationScope(instrumentation.Scope{
+			Name:       name,
+			Version:    version,
+			SchemaURL:  "http://this.is.mapped.elsewhere.com",
+			Attributes: attr,
+		})
+		assert.Equal(t, expected, actual)
+	})
+}
diff --git a/exporters/stdout/stdoutmetric/example_test.go b/exporters/stdout/stdoutmetric/example_test.go
@@ -142,7 +142,9 @@ func Example() {
 	//     {
 	//       "Scope": {
 	//         "Name": "example",
-	//         "Version": "v0.0.1"
+	//         "Version": "v0.0.1",
+	//         "SchemaURL": "",
+	//         "Attributes": null
 	//       },
 	//       "Metrics": [
 	//         {

diff --git a/exporters/stdout/stdouttrace/trace_test.go b/exporters/stdout/stdouttrace/trace_test.go
@@ -185,7 +185,9 @@ func expectedJSON(now time.Time) string {
 	],
 	"InstrumentationLibrary": {
 		"Name": "",
-		"Version": ""
+		"Version": "",
+		"SchemaURL": "",
+		"Attributes": null
 	}
 }
 `

diff --git a/metric/config.go b/metric/config.go
@@ -14,10 +14,13 @@
 
 package metric // import "go.opentelemetry.io/otel/metric"
 
+import "go.opentelemetry.io/otel/attribute"
+
 // MeterConfig contains options for Meters.
 type MeterConfig struct {
 	instrumentationVersion string
 	schemaURL              string
+	attributes             attribute.Set
 }
 
 // InstrumentationVersion is the version of the library providing instrumentation.
@@ -30,6 +33,11 @@ func (cfg MeterConfig) SchemaURL() string {
 	return cfg.schemaURL
 }
 
+// Attributes returns the scope attribute set of the Meter.
+func (t MeterConfig) Attributes() attribute.Set {
+	return t.attributes
+}
+
 // MeterOption is an interface for applying Meter options.
 type MeterOption interface {
 	// applyMeter is used to set a MeterOption value of a MeterConfig.
@@ -67,3 +75,13 @@ func WithSchemaURL(schemaURL string) MeterOption {
 		return config
 	})
 }
+
+// WithScopeAttributes sets the attributes for the scope of a Meter. The
+// attributes are stored as an attribute set. Duplicate values are removed, the
+// last value is used.
+func WithScopeAttributes(attr ...attribute.KeyValue) MeterOption {
+	return meterOptionFunc(func(cfg MeterConfig) MeterConfig {
+		cfg.attributes = attribute.NewSet(attr...)
+		return cfg
+	})
+}
diff --git a/metric/config_test.go b/metric/config_test.go
@@ -0,0 +1,69 @@
+// 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 metric // import "go.opentelemetry.io/otel/metric"
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"go.opentelemetry.io/otel/attribute"
+)
+
+func TestMeterConfig(t *testing.T) {
+	t.Run("Empty", func(t *testing.T) {
+		assert.Equal(t, NewMeterConfig(), MeterConfig{})
+	})
+
+	t.Run("InstrumentationVersion", func(t *testing.T) {
+		v0, v1 := "v0.1.0", "v1.0.0"
+
+		assert.Equal(t, NewMeterConfig(
+			WithInstrumentationVersion(v0),
+		).InstrumentationVersion(), v0)
+
+		assert.Equal(t, NewMeterConfig(
+			WithInstrumentationVersion(v0),
+			WithInstrumentationVersion(v1),
+		).InstrumentationVersion(), v1, "last option has precedence")
+	})
+
+	t.Run("SchemaURL", func(t *testing.T) {
+		s120 := "https://opentelemetry.io/schemas/1.2.0"
+		s130 := "https://opentelemetry.io/schemas/1.3.0"
+
+		assert.Equal(t, NewMeterConfig(
+			WithSchemaURL(s120),
+		).SchemaURL(), s120)
+
+		assert.Equal(t, NewMeterConfig(
+			WithSchemaURL(s120),
+			WithSchemaURL(s130),
+		).SchemaURL(), s130, "last option has precedence")
+	})
+
+	t.Run("Attributes", func(t *testing.T) {
+		one, two := attribute.Int("key", 1), attribute.Int("key", 2)
+
+		assert.Equal(t, NewMeterConfig(
+			WithScopeAttributes(one, two),
+		).Attributes(), attribute.NewSet(two), "last attribute is used")
+
+		assert.Equal(t, NewMeterConfig(
+			WithScopeAttributes(two),
+			WithScopeAttributes(one),
+		).Attributes(), attribute.NewSet(one), "last option has precedence")
+	})
+}
diff --git a/metric/meter.go b/metric/meter.go
@@ -24,15 +24,50 @@ import (
 	"go.opentelemetry.io/otel/metric/instrument/syncint64"
 )
 
-// MeterProvider provides access to named Meter instances, for instrumenting
-// an application or library.
+// MeterProvider provides Meters that are used by instrumentation code to
+// create instruments that measure code operations.
+//
+// A MeterProvider is the collection destination of all measurements made from
+// instruments the provided Meters created, it represents a unique telemetry
+// collection pipeline. How that pipeline is defined, meaning how those
+// measurements are collected, processed, and where they are exported, depends
+// on its implementation. Instrumentation authors do not need to define this
+// implementation, rather just use the provided Meters to instrument code.
+//
+// Commonly, instrumentation code will accept a MeterProvider implementation at
+// runtime from its users or it can simply use the globally registered one (see
+// https://pkg.go.dev/go.opentelemetry.io/otel/metric/global#MeterProvider).
+//
+// Warning: methods may be added to this interface in minor releases.
 type MeterProvider interface {
-	// Meter creates an instance of a `Meter` 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.
-	Meter(instrumentationName string, opts ...MeterOption) Meter
+	// Meter returns a unique Meter scoped to be used by instrumentation code
+	// to measure code operations. The scope and identity of that
+	// instrumentation code is uniquely defined by the name and options passed.
+	//
+	// The passed name needs to uniquely identify instrumentation code.
+	// Therefore, it is recommended that name is the Go package name of the
+	// library providing instrumentation (note: not the code being
+	// instrumented). Instrumentation libraries can have multiple versions,
+	// therefore, the WithInstrumentationVersion option should be used to
+	// distinguish these different codebases. Additionally, instrumentation
+	// libraries may sometimes use metric measurements to communicate different
+	// domains of code operations data (i.e. using different Meters to
+	// communicate user experience and back-end operations). If this is the
+	// case, the WithScopeAttributes option should be used to uniquely identify
+	// Meters that handle the different domains of code operations data.
+	//
+	// If the same name and options are passed multiple times, the same Meter
+	// will be returned (it is up to the implementation if this will be the
+	// same underlying instance of that Meter or not). It is not necessary to
+	// call this multiple times with the same name and options to get an
+	// up-to-date Meter. All implementations will ensure any MeterProvider
+	// configuration changes are propagated to all provided Meters.
+	//
+	// If name is empty, then an implementation defined default name will be
+	// used instead.
+	//
+	// This method is safe to call concurrently.
+	Meter(name string, options ...MeterOption) Meter
 }
 
 // Meter provides access to instrument instances for recording metrics.

diff --git a/sdk/instrumentation/doc.go b/sdk/instrumentation/doc.go
@@ -0,0 +1,24 @@
+// 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 types to represent the code libraries that
+// provide OpenTelemetry instrumentation. These types are used in the
+// OpenTelemetry signal pipelines to identify the source of telemetry.
+//
+// See
+// https://github.com/open-telemetry/oteps/blob/d226b677d73a785523fe9b9701be13225ebc528d/text/0083-component.md
+// and
+// https://github.com/open-telemetry/oteps/blob/d226b677d73a785523fe9b9701be13225ebc528d/text/0201-scope-attributes.md
+// for more information.
+package instrumentation // import "go.opentelemetry.io/otel/sdk/instrumentation"
diff --git a/sdk/instrumentation/library.go b/sdk/instrumentation/library.go
@@ -12,13 +12,6 @@
 // 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/main/text/0083-component.md).
-*/
 package instrumentation // import "go.opentelemetry.io/otel/sdk/instrumentation"
 
 // Library represents the instrumentation library.