feat(telemetry): instrument inference duration and frame age

vendor/go.opentelemetry.io/otel/metric/sdkapi/descriptor.go

@@ -0,0 +1,70 @@
+// 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 sdkapi // import "go.opentelemetry.io/otel/metric/sdkapi"
+
+import (
+	"go.opentelemetry.io/otel/metric/number"
+	"go.opentelemetry.io/otel/metric/unit"
+)
+
+// Descriptor contains all the settings that describe an instrument,
+// including its name, metric kind, number kind, and the configurable
+// options.
+type Descriptor struct {
+	name           string
+	instrumentKind InstrumentKind
+	numberKind     number.Kind
+	description    string
+	unit           unit.Unit
+}
+
+// NewDescriptor returns a Descriptor with the given contents.
+func NewDescriptor(name string, ikind InstrumentKind, nkind number.Kind, description string, unit unit.Unit) Descriptor {
+	return Descriptor{
+		name:           name,
+		instrumentKind: ikind,
+		numberKind:     nkind,
+		description:    description,
+		unit:           unit,
+	}
+}
+
+// Name returns the metric instrument's name.
+func (d Descriptor) Name() string {
+	return d.name
+}
+
+// InstrumentKind returns the specific kind of instrument.
+func (d Descriptor) InstrumentKind() InstrumentKind {
+	return d.instrumentKind
+}
+
+// Description provides a human-readable description of the metric
+// instrument.
+func (d Descriptor) Description() string {
+	return d.description
+}
+
+// Unit describes the units of the metric instrument.  Unitless
+// metrics return the empty string.
+func (d Descriptor) Unit() unit.Unit {
+	return d.unit
+}
+
+// NumberKind returns whether this instrument is declared over int64,
+// float64, or uint64 values.
+func (d Descriptor) NumberKind() number.Kind {
+	return d.numberKind
+}

vendor/go.opentelemetry.io/otel/metric/sdkapi/instrumentkind.go

@@ -0,0 +1,80 @@
+// 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.
+
+//go:generate stringer -type=InstrumentKind
+
+package sdkapi // import "go.opentelemetry.io/otel/metric/sdkapi"
+
+// InstrumentKind describes the kind of instrument.
+type InstrumentKind int8
+
+const (
+	// HistogramInstrumentKind indicates a Histogram instrument.
+	HistogramInstrumentKind InstrumentKind = iota
+	// GaugeObserverInstrumentKind indicates an GaugeObserver instrument.
+	GaugeObserverInstrumentKind
+
+	// CounterInstrumentKind indicates a Counter instrument.
+	CounterInstrumentKind
+	// UpDownCounterInstrumentKind indicates a UpDownCounter instrument.
+	UpDownCounterInstrumentKind
+
+	// CounterObserverInstrumentKind indicates a CounterObserver instrument.
+	CounterObserverInstrumentKind
+	// UpDownCounterObserverInstrumentKind indicates a UpDownCounterObserver
+	// instrument.
+	UpDownCounterObserverInstrumentKind
+)
+
+// Synchronous returns whether this is a synchronous kind of instrument.
+func (k InstrumentKind) Synchronous() bool {
+	switch k {
+	case CounterInstrumentKind, UpDownCounterInstrumentKind, HistogramInstrumentKind:
+		return true
+	}
+	return false
+}
+
+// Asynchronous returns whether this is an asynchronous kind of instrument.
+func (k InstrumentKind) Asynchronous() bool {
+	return !k.Synchronous()
+}
+
+// Adding returns whether this kind of instrument adds its inputs (as opposed to Grouping).
+func (k InstrumentKind) Adding() bool {
+	switch k {
+	case CounterInstrumentKind, UpDownCounterInstrumentKind, CounterObserverInstrumentKind, UpDownCounterObserverInstrumentKind:
+		return true
+	}
+	return false
+}
+
+// Grouping returns whether this kind of instrument groups its inputs (as opposed to Adding).
+func (k InstrumentKind) Grouping() bool {
+	return !k.Adding()
+}
+
+// Monotonic returns whether this kind of instrument exposes a non-decreasing sum.
+func (k InstrumentKind) Monotonic() bool {
+	switch k {
+	case CounterInstrumentKind, CounterObserverInstrumentKind:
+		return true
+	}
+	return false
+}
+
+// PrecomputedSum returns whether this kind of instrument receives precomputed sums.
+func (k InstrumentKind) PrecomputedSum() bool {
+	return k.Adding() && k.Asynchronous()
+}

vendor/go.opentelemetry.io/otel/metric/sdkapi/instrumentkind_string.go

@@ -0,0 +1,28 @@
+// Code generated by "stringer -type=InstrumentKind"; DO NOT EDIT.
+
+package sdkapi
+
+import "strconv"
+
+func _() {
+	// An "invalid array index" compiler error signifies that the constant values have changed.
+	// Re-run the stringer command to generate them again.
+	var x [1]struct{}
+	_ = x[HistogramInstrumentKind-0]
+	_ = x[GaugeObserverInstrumentKind-1]
+	_ = x[CounterInstrumentKind-2]
+	_ = x[UpDownCounterInstrumentKind-3]
+	_ = x[CounterObserverInstrumentKind-4]
+	_ = x[UpDownCounterObserverInstrumentKind-5]
+}
+
+const _InstrumentKind_name = "HistogramInstrumentKindGaugeObserverInstrumentKindCounterInstrumentKindUpDownCounterInstrumentKindCounterObserverInstrumentKindUpDownCounterObserverInstrumentKind"
+
+var _InstrumentKind_index = [...]uint8{0, 23, 50, 71, 98, 127, 162}
+
+func (i InstrumentKind) String() string {
+	if i < 0 || i >= InstrumentKind(len(_InstrumentKind_index)-1) {
+		return "InstrumentKind(" + strconv.FormatInt(int64(i), 10) + ")"
+	}
+	return _InstrumentKind_name[_InstrumentKind_index[i]:_InstrumentKind_index[i+1]]
+}

vendor/go.opentelemetry.io/otel/metric/sdkapi/noop.go

@@ -0,0 +1,64 @@
+// 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 sdkapi // import "go.opentelemetry.io/otel/metric/sdkapi"
+
+import (
+	"context"
+
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/metric/number"
+)
+
+type noopInstrument struct{}
+type noopBoundInstrument struct{}
+type noopSyncInstrument struct{ noopInstrument }
+type noopAsyncInstrument struct{ noopInstrument }
+
+var _ SyncImpl = noopSyncInstrument{}
+var _ BoundSyncImpl = noopBoundInstrument{}
+var _ AsyncImpl = noopAsyncInstrument{}
+
+// NewNoopSyncInstrument returns a No-op implementation of the
+// synchronous instrument interface.
+func NewNoopSyncInstrument() SyncImpl {
+	return noopSyncInstrument{}
+}
+
+// NewNoopAsyncInstrument returns a No-op implementation of the
+// asynchronous instrument interface.
+func NewNoopAsyncInstrument() AsyncImpl {
+	return noopAsyncInstrument{}
+}
+
+func (noopInstrument) Implementation() interface{} {
+	return nil
+}
+
+func (noopInstrument) Descriptor() Descriptor {
+	return Descriptor{}
+}
+
+func (noopBoundInstrument) RecordOne(context.Context, number.Number) {
+}
+
+func (noopBoundInstrument) Unbind() {
+}
+
+func (noopSyncInstrument) Bind([]attribute.KeyValue) BoundSyncImpl {
+	return noopBoundInstrument{}
+}
+
+func (noopSyncInstrument) RecordOne(context.Context, number.Number, []attribute.KeyValue) {
+}

vendor/go.opentelemetry.io/otel/metric/sdkapi/sdkapi.go

@@ -0,0 +1,175 @@
+// 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 sdkapi // import "go.opentelemetry.io/otel/metric/sdkapi"
+
+import (
+	"context"
+
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/metric/number"
+)
+
+// MeterImpl is the interface an SDK must implement to supply a Meter
+// implementation.
+type MeterImpl interface {
+	// RecordBatch atomically records a batch of measurements.
+	RecordBatch(ctx context.Context, labels []attribute.KeyValue, measurement ...Measurement)
+
+	// NewSyncInstrument returns a newly constructed
+	// synchronous instrument implementation or an error, should
+	// one occur.
+	NewSyncInstrument(descriptor Descriptor) (SyncImpl, error)
+
+	// NewAsyncInstrument returns a newly constructed
+	// asynchronous instrument implementation or an error, should
+	// one occur.
+	NewAsyncInstrument(
+		descriptor Descriptor,
+		runner AsyncRunner,
+	) (AsyncImpl, error)
+}
+
+// InstrumentImpl is a common interface for synchronous and
+// asynchronous instruments.
+type InstrumentImpl interface {
+	// Implementation returns the underlying implementation of the
+	// instrument, which allows the implementation to gain access
+	// to its own representation especially from a `Measurement`.
+	Implementation() interface{}
+
+	// Descriptor returns a copy of the instrument's Descriptor.
+	Descriptor() Descriptor
+}
+
+// SyncImpl is the implementation-level interface to a generic
+// synchronous instrument (e.g., Histogram and Counter instruments).
+type SyncImpl interface {
+	InstrumentImpl
+
+	// Bind creates an implementation-level bound instrument,
+	// binding a label set with this instrument implementation.
+	Bind(labels []attribute.KeyValue) BoundSyncImpl
+
+	// RecordOne captures a single synchronous metric event.
+	RecordOne(ctx context.Context, number number.Number, labels []attribute.KeyValue)
+}
+
+// BoundSyncImpl is the implementation-level interface to a
+// generic bound synchronous instrument
+type BoundSyncImpl interface {
+
+	// RecordOne captures a single synchronous metric event.
+	RecordOne(ctx context.Context, number number.Number)
+
+	// Unbind frees the resources associated with this bound instrument. It
+	// does not affect the metric this bound instrument was created through.
+	Unbind()
+}
+
+// AsyncImpl is an implementation-level interface to an
+// asynchronous instrument (e.g., Observer instruments).
+type AsyncImpl interface {
+	InstrumentImpl
+}
+
+// AsyncRunner is expected to convert into an AsyncSingleRunner or an
+// AsyncBatchRunner.  SDKs will encounter an error if the AsyncRunner
+// does not satisfy one of these interfaces.
+type AsyncRunner interface {
+	// AnyRunner() is a non-exported method with no functional use
+	// other than to make this a non-empty interface.
+	AnyRunner()
+}
+
+// AsyncSingleRunner is an interface implemented by single-observer
+// callbacks.
+type AsyncSingleRunner interface {
+	// Run accepts a single instrument and function for capturing
+	// observations of that instrument.  Each call to the function
+	// receives one captured observation.  (The function accepts
+	// multiple observations so the same implementation can be
+	// used for batch runners.)
+	Run(ctx context.Context, single AsyncImpl, capture func([]attribute.KeyValue, ...Observation))
+
+	AsyncRunner
+}
+
+// AsyncBatchRunner is an interface implemented by batch-observer
+// callbacks.
+type AsyncBatchRunner interface {
+	// Run accepts a function for capturing observations of
+	// multiple instruments.
+	Run(ctx context.Context, capture func([]attribute.KeyValue, ...Observation))
+
+	AsyncRunner
+}
+
+// NewMeasurement constructs a single observation, a binding between
+// an asynchronous instrument and a number.
+func NewMeasurement(instrument SyncImpl, number number.Number) Measurement {
+	return Measurement{
+		instrument: instrument,
+		number:     number,
+	}
+}
+
+// Measurement is a low-level type used with synchronous instruments
+// as a direct interface to the SDK via `RecordBatch`.
+type Measurement struct {
+	// number needs to be aligned for 64-bit atomic operations.
+	number     number.Number
+	instrument SyncImpl
+}
+
+// SyncImpl returns the instrument that created this measurement.
+// This returns an implementation-level object for use by the SDK,
+// users should not refer to this.
+func (m Measurement) SyncImpl() SyncImpl {
+	return m.instrument
+}
+
+// Number returns a number recorded in this measurement.
+func (m Measurement) Number() number.Number {
+	return m.number
+}
+
+// NewObservation constructs a single observation, a binding between
+// an asynchronous instrument and a number.
+func NewObservation(instrument AsyncImpl, number number.Number) Observation {
+	return Observation{
+		instrument: instrument,
+		number:     number,
+	}
+}
+
+// Observation is a low-level type used with asynchronous instruments
+// as a direct interface to the SDK via `BatchObserver`.
+type Observation struct {
+	// number needs to be aligned for 64-bit atomic operations.
+	number     number.Number
+	instrument AsyncImpl
+}
+
+// AsyncImpl returns the instrument that created this observation.
+// This returns an implementation-level object for use by the SDK,
+// users should not refer to this.
+func (m Observation) AsyncImpl() AsyncImpl {
+	return m.instrument
+}
+
+// Number returns a number recorded in this observation.
+func (m Observation) Number() number.Number {
+	return m.number
+}