Add View, NewView, Instrument, Stream, and InstrumentKind to sdk/metric with unit tests

CHANGELOG.md

@@ -24,6 +24,11 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   - `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`
   - `OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE`
   - `OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE`
+- The `View` type and related `NewView` function to create a view according to the OpenTelemetry specification are added to `go.opentelemetry.io/otel/sdk/metric`.
+  These additions are uses as replacements for the `View` type and `New` function from `go.opentelemetry.io/otel/sdk/metric/view`. (#3459)
+- The `Instrument` and `InstrumentKind` type are added to `go.opentelemetry.io/otel/sdk/metric`.
+  These additions are uses as replacements for the `Instrument` and `InstrumentKind` types from `go.opentelemetry.io/otel/sdk/metric/view`. (#3459)
+- The `Stream` type is added to `go.opentelemetry.io/otel/sdk/metric` to define a metric data stream a view will produce. (#3459)
 
 ### Changed
 

sdk/metric/instrument.go

@@ -24,10 +24,157 @@ import (
 	"go.opentelemetry.io/otel/metric/instrument/syncfloat64"
 	"go.opentelemetry.io/otel/metric/instrument/syncint64"
 	"go.opentelemetry.io/otel/metric/unit"
+	"go.opentelemetry.io/otel/sdk/instrumentation"
+	"go.opentelemetry.io/otel/sdk/metric/aggregation"
 	"go.opentelemetry.io/otel/sdk/metric/internal"
 	"go.opentelemetry.io/otel/sdk/metric/metricdata"
 )
 
+var (
+	zeroUnit           unit.Unit
+	zeroInstrumentKind InstrumentKind
+	zeroScope          instrumentation.Scope
+)
+
+// InstrumentKind is the identifier of a group of instruments that all
+// performing the same function.
+type InstrumentKind uint8
+
+const (
+	// instrumentKindUndefined is an undefined instrument kind, it should not
+	// be used by any initialized type.
+	instrumentKindUndefined InstrumentKind = iota // nolint:deadcode,varcheck,unused
+	// InstrumentKindSyncCounter identifies a group of instruments that record
+	// increasing values synchronously with the code path they are measuring.
+	InstrumentKindSyncCounter
+	// InstrumentKindSyncUpDownCounter identifies a group of instruments that
+	// record increasing and decreasing values synchronously with the code path
+	// they are measuring.
+	InstrumentKindSyncUpDownCounter
+	// InstrumentKindSyncHistogram identifies a group of instruments that
+	// record a distribution of values synchronously with the code path they
+	// are measuring.
+	InstrumentKindSyncHistogram
+	// InstrumentKindAsyncCounter identifies a group of instruments that record
+	// increasing values in an asynchronous callback.
+	InstrumentKindAsyncCounter
+	// InstrumentKindAsyncUpDownCounter identifies a group of instruments that
+	// record increasing and decreasing values in an asynchronous callback.
+	InstrumentKindAsyncUpDownCounter
+	// InstrumentKindAsyncGauge identifies a group of instruments that record
+	// current values in an asynchronous callback.
+	InstrumentKindAsyncGauge
+)
+
+type nonComparable [0]func() // nolint: unused  // This is indeed used.
+
+// Instrument describes properties an instrument is created with.
+type Instrument struct {
+	// Name is the human-readable identifier of the instrument.
+	Name string
+	// Description describes the purpose of the instrument.
+	Description string
+	// Kind defines the functional group of the instrument.
+	Kind InstrumentKind
+	// Unit is the unit of measurement recorded by the instrument.
+	Unit unit.Unit
+	// Scope identifies the instrumentation that created the instrument.
+	Scope instrumentation.Scope
+
+	// Ensure forward compatibility if non-comparable fields need to be added.
+	nonComparable // nolint: unused
+}
+
+// mask returns a copy of p with all non-zero-value fields of m replacing the
+// fields of the returned copy.
+func (p Instrument) mask(m Instrument) Instrument {
+	if m.Name != "" {
+		p.Name = m.Name
+	}
+	if m.Description != "" {
+		p.Description = m.Description
+	}
+	if m.Kind != zeroInstrumentKind {
+		p.Kind = m.Kind
+	}
+	if m.Unit != zeroUnit {
+		p.Unit = m.Unit
+	}
+	if m.Scope.Name != "" {
+		p.Scope.Name = m.Scope.Name
+	}
+	if m.Scope.Version != "" {
+		p.Scope.Version = m.Scope.Version
+	}
+	if m.Scope.SchemaURL != "" {
+		p.Scope.SchemaURL = m.Scope.SchemaURL
+	}
+	return p
+}
+
+// empty returns if all fields of p are their zero-value.
+func (p Instrument) empty() bool {
+	return p.Name == "" &&
+		p.Description == "" &&
+		p.Kind == zeroInstrumentKind &&
+		p.Unit == zeroUnit &&
+		p.Scope == zeroScope
+}
+
+// matches returns if all the non-zero-value fields of o match the
+// corresponding fields of p.
+//
+// If o is empty true is returned.
+func (p Instrument) matches(o Instrument) bool {
+	return p.matchesName(o) &&
+		p.matchesDescription(o) &&
+		p.matchesKind(o) &&
+		p.matchesUnit(o) &&
+		p.matchesScope(o)
+}
+
+// matchesName returns true if the Name field of o is a non-zero-value and
+// equals the Name field of p, otherwise false.
+func (p Instrument) matchesName(o Instrument) bool {
+	return p.Name == "" || p.Name == o.Name
+}
+
+// matchesDescription returns true if the Description field of o is a
+// non-zero-value and equals the Description field of p, otherwise false.
+func (p Instrument) matchesDescription(o Instrument) bool {
+	return p.Description == "" || p.Description == o.Description
+}
+
+// matchesKind returns true if the Kind field of o is a non-zero-value and
+// equals the Kind field of p, otherwise false.
+func (p Instrument) matchesKind(o Instrument) bool {
+	return p.Kind == zeroInstrumentKind || p.Kind == o.Kind
+}
+
+// matchesUnit returns true if the Unit field of o is a non-zero-value and
+// equals the Unit field of p, otherwise false.
+func (p Instrument) matchesUnit(o Instrument) bool {
+	return p.Unit == zeroUnit || p.Unit == o.Unit
+}
+
+// matchesScope returns true if the Scope field of o is a non-zero-value and
+// equals the Scope field of p, otherwise false.
+func (p Instrument) matchesScope(o Instrument) bool {
+	return (p.Scope.Name == "" || p.Scope.Name == o.Scope.Name) &&
+		(p.Scope.Version == "" || p.Scope.Version == o.Scope.Version) &&
+		(p.Scope.SchemaURL == "" || p.Scope.SchemaURL == o.Scope.SchemaURL)
+}
+
+// Stream describes the stream of data an instrument produces.
+type Stream struct {
+	Instrument
+
+	// Aggregation the stream uses for an instrument.
+	Aggregation aggregation.Aggregation
+	// AttributeFilter applied to all attributes recorded for an instrument.
+	AttributeFilter attribute.Filter
+}
+
 // instrumentID are the identifying properties of an instrument.
 type instrumentID struct {
 	// Name is the name of the instrument.

sdk/metric/pipeline_registry_test.go

@@ -369,6 +369,7 @@ func TestPipelineRegistryCreateAggregatorsIncompatibleInstrument(t *testing.T) {
 type logCounter struct {
 	logr.LogSink
 
+	errN  uint32
 	infoN uint32
 }
 
@@ -381,6 +382,15 @@ func (l *logCounter) InfoN() int {
 	return int(atomic.SwapUint32(&l.infoN, 0))
 }
 
+func (l *logCounter) Error(err error, msg string, keysAndValues ...interface{}) {
+	atomic.AddUint32(&l.errN, 1)
+	l.LogSink.Error(err, msg, keysAndValues...)
+}
+
+func (l *logCounter) ErrorN() int {
+	return int(atomic.SwapUint32(&l.errN, 0))
+}
+
 func TestResolveAggregatorsDuplicateErrors(t *testing.T) {
 	tLog := testr.NewWithOptions(t, testr.Options{Verbosity: 6})
 	l := &logCounter{LogSink: tLog.GetSink()}

sdk/metric/view.go

@@ -0,0 +1,95 @@
+// 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/sdk/metric"
+
+import (
+	"regexp"
+	"strings"
+
+	"go.opentelemetry.io/otel/internal/global"
+	"go.opentelemetry.io/otel/sdk/metric/aggregation"
+)
+
+// View is an override to the default behavior of the SDK. It defines how data
+// should be collected for certain instruments. It returns true and the exact
+// Stream to use for matching Instruments. Otherwise, if the view does not
+// match, false is returned.
+type View func(Instrument) (Stream, bool)
+
+// NewView returns a View that applies the Stream mask for all instruments that
+// match criteria. The returned View will only apply mask if all non-zero-value
+// fields of criteria match the corresponding Instrument passed to the view. If
+// no criteria are provided, all field of criteria are their zero-values, a
+// view that matches no instruments is returned.
+//
+// The Name field of criteria supports wildcard pattern matching. The wildcard
+// "*" is recognized as matching zero or more characters, and "?" is recognized
+// as matching exactly one character. For example, a pattern of "*" will match
+// all instrument names.
+//
+// The Stream mask only applies updates for non-zero-value fields. By default,
+// the Instrument the View matches against will be use for the returned Stream
+// and no Aggregation or AttributeFilter are set. If mask has a non-zero-value
+// value for any of the Aggregation or AttributeFilter fields, or any of the
+// Instrument fields, that value is used instead of the default. If you need to
+// zero out an Stream field returned from a View, create a View directly.
+func NewView(criteria Instrument, mask Stream) View {
+	if criteria.empty() {
+		return func(Instrument) (Stream, bool) { return Stream{}, false }
+	}
+
+	var matchFunc func(Instrument) bool
+	if strings.ContainsAny(criteria.Name, "*?") {
+		pattern := regexp.QuoteMeta(criteria.Name)
+		pattern = "^" + pattern + "$"
+		pattern = strings.ReplaceAll(pattern, "\\?", ".")
+		pattern = strings.ReplaceAll(pattern, "\\*", ".*")
+		re := regexp.MustCompile(pattern)
+		matchFunc = func(p Instrument) bool {
+			return re.MatchString(p.Name) &&
+				criteria.matchesDescription(p) &&
+				criteria.matchesKind(p) &&
+				criteria.matchesUnit(p) &&
+				criteria.matchesScope(p)
+		}
+	} else {
+		matchFunc = criteria.matches
+	}
+
+	var agg aggregation.Aggregation
+	if mask.Aggregation != nil {
+		agg = mask.Aggregation.Copy()
+		if err := agg.Err(); err != nil {
+			global.Error(
+				err, "not using aggregation with view",
+				"aggregation", agg,
+				"view", criteria,
+			)
+			agg = nil
+		}
+	}
+
+	return func(p Instrument) (Stream, bool) {
+		if matchFunc(p) {
+			stream := Stream{
+				Instrument:      p.mask(mask.Instrument),
+				Aggregation:     agg,
+				AttributeFilter: mask.AttributeFilter,
+			}
+			return stream, true
+		}
+		return Stream{}, false
+	}
+}