Merge branch 'main' into mvg/otlp-clientless

CHANGELOG.md

@@ -58,6 +58,12 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - The `go.opentelemetry.io/otel/exporters/otlp/otlpmetric.Client` interface is removed. (#3486)
 - The `go.opentelemetry.io/otel/exporters/otlp/otlpmetric.New` function is removed. Use the `otlpmetric[http|grpc].New` directly. (#3486)
 
+### Deprecated
+
+- The `go.opentelemetry.io/otel/sdk/metric/view` package is deprecated.
+  Use `Instrument`, `InstrumentKind`, `View`, and `NewView` in `go.opentelemetry.io/otel/sdk/metric` instead. (#3476)
+
+
 ## [1.11.1/0.33.0] 2022-10-19
 
 ### Added

sdk/metric/view/doc.go

@@ -17,4 +17,7 @@
 // registered with a MeterProvider in the go.opentelemetry.io/otel/sdk/metric
 // package. See the WithReader option in that package for more information on
 // how this registration takes place.
+//
+// Deprecated: Use Instrument, InstrumentKind, View, and NewView in
+// go.opentelemetry.io/otel/sdk/metric instead.
 package view // import "go.opentelemetry.io/otel/sdk/metric/view"

sdk/metric/view/instrument.go

@@ -20,6 +20,8 @@ import (
 )
 
 // Instrument uniquely identifies an instrument within a meter.
+//
+// Deprecated: Use Instrument in go.opentelemetry.io/otel/sdk/metric instead.
 type Instrument struct {
 	Scope instrumentation.Scope
 

sdk/metric/view/instrumentkind.go

@@ -15,6 +15,9 @@
 package view // import "go.opentelemetry.io/otel/sdk/metric/view"
 
 // InstrumentKind describes the kind of instrument a Meter can create.
+//
+// Deprecated: Use InstrumentKind in go.opentelemetry.io/otel/sdk/metric
+// instead.
 type InstrumentKind uint8
 
 // These are all the instrument kinds supported by the SDK.
@@ -24,20 +27,38 @@ const (
 	undefinedInstrument InstrumentKind = iota
 	// SyncCounter is an instrument kind that records increasing values
 	// synchronously in application code.
+	//
+	// Deprecated: Use InstrumentKindSyncCounter in
+	// go.opentelemetry.io/otel/sdk/metric instead.
 	SyncCounter
 	// SyncUpDownCounter is an instrument kind that records increasing and
 	// decreasing values synchronously in application code.
+	//
+	// Deprecated: Use InstrumentKindSyncUpDownCounter in
+	// go.opentelemetry.io/otel/sdk/metric instead.
 	SyncUpDownCounter
 	// SyncHistogram is an instrument kind that records a distribution of
 	// values synchronously in application code.
+	//
+	// Deprecated: Use InstrumentKindSyncHistogram in
+	// go.opentelemetry.io/otel/sdk/metric instead.
 	SyncHistogram
 	// AsyncCounter is an instrument kind that records increasing values in an
 	// asynchronous callback.
+	//
+	// Deprecated: Use InstrumentKindAsyncCounter in
+	// go.opentelemetry.io/otel/sdk/metric instead.
 	AsyncCounter
 	// AsyncUpDownCounter is an instrument kind that records increasing and
 	// decreasing values in an asynchronous callback.
+	//
+	// Deprecated: Use InstrumentKindAsyncUpDownCounter in
+	// go.opentelemetry.io/otel/sdk/metric instead.
 	AsyncUpDownCounter
 	// AsyncGauge is an instrument kind that records current values in an
 	// asynchronous callback.
+	//
+	// Deprecated: Use InstrumentKindAsyncGauge in
+	// go.opentelemetry.io/otel/sdk/metric instead.
 	AsyncGauge
 )

sdk/metric/view/view.go

@@ -31,6 +31,8 @@ import (
 // reported by Instruments.
 //
 // An empty View will match all instruments, and do no transformations.
+//
+// Deprecated: Use View in go.opentelemetry.io/otel/sdk/metric instead.
 type View struct {
 	instrumentName *regexp.Regexp
 	hasWildcard    bool
@@ -48,6 +50,8 @@ type View struct {
 // Options are all applied to the View. An instrument needs to match all of
 // the match Options passed for the View to be applied to it. Similarly, all
 // transform operation Options are applied to matched Instruments.
+//
+// Deprecated: Use NewView in go.opentelemetry.io/otel/sdk/metric instead.
 func New(opts ...Option) (View, error) {
 	v := View{}
 

sdk/metric/view_test.go

@@ -15,6 +15,8 @@
 package metric // import "go.opentelemetry.io/otel/sdk/metric"
 
 import (
+	"fmt"
+	"regexp"
 	"testing"
 
 	"github.com/go-logr/logr"
@@ -469,3 +471,134 @@ func TestNewViewAggregationErrorLogged(t *testing.T) {
 	assert.Nil(t, got.Aggregation, "erroring aggregation used")
 	assert.Equal(t, 1, l.ErrorN())
 }
+
+func ExampleNewView() {
+	// Create a view that renames the "latency" instrument from the v0.34.0
+	// version of the "http" instrumentation library as "request.latency".
+	view := NewView(Instrument{
+		Name: "latency",
+		Scope: instrumentation.Scope{
+			Name:    "http",
+			Version: "v0.34.0",
+		},
+	}, Stream{Name: "request.latency"})
+
+	// The created view can then be registered with the OpenTelemetry metric
+	// SDK using the WithView option. Below is an example of how the view will
+	// function in the SDK for certain instruments.
+
+	stream, _ := view(Instrument{
+		Name:        "latency",
+		Description: "request latency",
+		Unit:        unit.Milliseconds,
+		Kind:        InstrumentKindSyncCounter,
+		Scope: instrumentation.Scope{
+			Name:      "http",
+			Version:   "v0.34.0",
+			SchemaURL: "https://opentelemetry.io/schemas/1.0.0",
+		},
+	})
+	fmt.Println("name:", stream.Name)
+	fmt.Println("description:", stream.Description)
+	fmt.Println("unit:", stream.Unit)
+	// Output:
+	// name: request.latency
+	// description: request latency
+	// unit: ms
+}
+
+func ExampleNewView_drop() {
+	// Create a view that sets the drop aggregator for all instrumentation from
+	// the "db" library, effectively turning-off all instrumentation from that
+	// library.
+	view := NewView(
+		Instrument{Scope: instrumentation.Scope{Name: "db"}},
+		Stream{Aggregation: aggregation.Drop{}},
+	)
+
+	// The created view can then be registered with the OpenTelemetry metric
+	// SDK using the WithView option. Below is an example of how the view will
+	// function in the SDK for certain instruments.
+
+	stream, _ := view(Instrument{
+		Name:  "queries",
+		Kind:  InstrumentKindSyncCounter,
+		Scope: instrumentation.Scope{Name: "db", Version: "v0.4.0"},
+	})
+	fmt.Println("name:", stream.Name)
+	fmt.Printf("aggregation: %#v", stream.Aggregation)
+	// Output:
+	// name: queries
+	// aggregation: aggregation.Drop{}
+}
+
+func ExampleNewView_wildcard() {
+	// Create a view that sets unit to milliseconds for any instrument with a
+	// name suffix of ".ms".
+	view := NewView(
+		Instrument{Name: "*.ms"},
+		Stream{Unit: unit.Milliseconds},
+	)
+
+	// The created view can then be registered with the OpenTelemetry metric
+	// SDK using the WithView option. Below is an example of how the view
+	// function in the SDK for certain instruments.
+
+	stream, _ := view(Instrument{
+		Name: "computation.time.ms",
+		Unit: unit.Dimensionless,
+	})
+	fmt.Println("name:", stream.Name)
+	fmt.Println("unit:", stream.Unit)
+	// Output:
+	// name: computation.time.ms
+	// unit: ms
+}
+
+func ExampleView() {
+	// The NewView function provides convenient creation of common Views
+	// construction. However, it is limited in what it can create.
+	//
+	// When NewView is not able to provide the functionally needed, a custom
+	// View can be constructed directly. Here a custom View is constructed that
+	// uses Go's regular expression matching to ensure all data stream names
+	// have a suffix of the units it uses.
+
+	re := regexp.MustCompile(`[._](ms|byte)$`)
+	var view View = func(i Instrument) (Stream, bool) {
+		s := Stream{Name: i.Name, Description: i.Description, Unit: i.Unit}
+		// Any instrument that does not have a unit suffix defined, but has a
+		// dimensional unit defined, update the name with a unit suffix.
+		if re.MatchString(i.Name) {
+			return s, false
+		}
+		switch i.Unit {
+		case unit.Milliseconds:
+			s.Name += ".ms"
+		case unit.Bytes:
+			s.Name += ".byte"
+		default:
+			return s, false
+		}
+		return s, true
+	}
+
+	// The created view can then be registered with the OpenTelemetry metric
+	// SDK using the WithView option. Below is an example of how the view will
+	// function in the SDK for certain instruments.
+
+	stream, _ := view(Instrument{
+		Name: "computation.time.ms",
+		Unit: unit.Milliseconds,
+	})
+	fmt.Println("name:", stream.Name)
+
+	stream, _ = view(Instrument{
+		Name: "heap.size",
+		Unit: unit.Bytes,
+	})
+	fmt.Println("name:", stream.Name)
+	// Output:
+	// name: computation.time.ms
+	// name: heap.size.byte
+}