Merge main into new_sdk/main

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
 

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)
+		})
+	}
+}

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()),
 	}
 }

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)
+	})
+}

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": [
 	//         {

exporters/stdout/stdouttrace/trace_test.go

@@ -185,7 +185,9 @@ func expectedJSON(now time.Time) string {
 	],
 	"InstrumentationLibrary": {
 		"Name": "",
-		"Version": ""
+		"Version": "",
+		"SchemaURL": "",
+		"Attributes": null
 	}
 }
 `

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
+	})
+}

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")
+	})
+}

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.

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"

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.