feat(telemetry): instrument inference duration and frame age

vendor/go.opentelemetry.io/otel/sdk/export/metric/aggregation/aggregation.go

@@ -0,0 +1,156 @@
+// 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 aggregation // import "go.opentelemetry.io/otel/sdk/export/metric/aggregation"
+
+import (
+	"fmt"
+	"time"
+
+	"go.opentelemetry.io/otel/metric/number"
+)
+
+// These interfaces describe the various ways to access state from an
+// Aggregation.
+
+type (
+	// Aggregation is an interface returned by the Aggregator
+	// containing an interval of metric data.
+	Aggregation interface {
+		// Kind returns a short identifying string to identify
+		// the Aggregator that was used to produce the
+		// Aggregation (e.g., "Sum").
+		Kind() Kind
+	}
+
+	// Sum returns an aggregated sum.
+	Sum interface {
+		Aggregation
+		Sum() (number.Number, error)
+	}
+
+	// Count returns the number of values that were aggregated.
+	Count interface {
+		Aggregation
+		Count() (uint64, error)
+	}
+
+	// Min returns the minimum value over the set of values that were aggregated.
+	Min interface {
+		Aggregation
+		Min() (number.Number, error)
+	}
+
+	// Max returns the maximum value over the set of values that were aggregated.
+	Max interface {
+		Aggregation
+		Max() (number.Number, error)
+	}
+
+	// LastValue returns the latest value that was aggregated.
+	LastValue interface {
+		Aggregation
+		LastValue() (number.Number, time.Time, error)
+	}
+
+	// Points returns the raw values that were aggregated.
+	Points interface {
+		Aggregation
+
+		// Points returns points in the order they were
+		// recorded.  Points are approximately ordered by
+		// timestamp, but this is not guaranteed.
+		Points() ([]Point, error)
+	}
+
+	// Point is a raw data point, consisting of a number and value.
+	Point struct {
+		number.Number
+		time.Time
+	}
+
+	// Buckets represents histogram buckets boundaries and counts.
+	//
+	// For a Histogram with N defined boundaries, e.g, [x, y, z].
+	// There are N+1 counts: [-inf, x), [x, y), [y, z), [z, +inf]
+	Buckets struct {
+		// Boundaries are floating point numbers, even when
+		// aggregating integers.
+		Boundaries []float64
+
+		// Counts holds the count in each bucket.
+		Counts []uint64
+	}
+
+	// Histogram returns the count of events in pre-determined buckets.
+	Histogram interface {
+		Aggregation
+		Count() (uint64, error)
+		Sum() (number.Number, error)
+		Histogram() (Buckets, error)
+	}
+
+	// MinMaxSumCount supports the Min, Max, Sum, and Count interfaces.
+	MinMaxSumCount interface {
+		Aggregation
+		Min() (number.Number, error)
+		Max() (number.Number, error)
+		Sum() (number.Number, error)
+		Count() (uint64, error)
+	}
+)
+
+type (
+	// Kind is a short name for the Aggregator that produces an
+	// Aggregation, used for descriptive purpose only.  Kind is a
+	// string to allow user-defined Aggregators.
+	//
+	// When deciding how to handle an Aggregation, Exporters are
+	// encouraged to decide based on conversion to the above
+	// interfaces based on strength, not on Kind value, when
+	// deciding how to expose metric data.  This enables
+	// user-supplied Aggregators to replace builtin Aggregators.
+	//
+	// For example, test for a Distribution before testing for a
+	// MinMaxSumCount, test for a Histogram before testing for a
+	// Sum, and so on.
+	Kind string
+)
+
+// Kind description constants.
+const (
+	SumKind            Kind = "Sum"
+	MinMaxSumCountKind Kind = "MinMaxSumCount"
+	HistogramKind      Kind = "Histogram"
+	LastValueKind      Kind = "Lastvalue"
+	ExactKind          Kind = "Exact"
+)
+
+// Sentinel errors for Aggregation interface.
+var (
+	ErrNegativeInput    = fmt.Errorf("negative value is out of range for this instrument")
+	ErrNaNInput         = fmt.Errorf("NaN value is an invalid input")
+	ErrInconsistentType = fmt.Errorf("inconsistent aggregator types")
+	ErrNoSubtraction    = fmt.Errorf("aggregator does not subtract")
+
+	// ErrNoData is returned when (due to a race with collection)
+	// the Aggregator is check-pointed before the first value is set.
+	// The aggregator should simply be skipped in this case.
+	ErrNoData = fmt.Errorf("no data collected by this aggregator")
+)
+
+// String returns the string value of Kind.
+func (k Kind) String() string {
+	return string(k)
+}

vendor/go.opentelemetry.io/otel/sdk/export/metric/aggregation/temporality.go

@@ -0,0 +1,117 @@
+// 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=Temporality
+
+package aggregation // import "go.opentelemetry.io/otel/sdk/export/metric/aggregation"
+
+import (
+	"go.opentelemetry.io/otel/metric/sdkapi"
+)
+
+// Temporality indicates the temporal aggregation exported by an exporter.
+// These bits may be OR-d together when multiple exporters are in use.
+type Temporality uint8
+
+const (
+	// CumulativeTemporality indicates that an Exporter expects a
+	// Cumulative Aggregation.
+	CumulativeTemporality Temporality = 1
+
+	// DeltaTemporality indicates that an Exporter expects a
+	// Delta Aggregation.
+	DeltaTemporality Temporality = 2
+)
+
+// Includes returns if t includes support for other temporality.
+func (t Temporality) Includes(other Temporality) bool {
+	return t&other != 0
+}
+
+// MemoryRequired returns whether an exporter of this temporality requires
+// memory to export correctly.
+func (t Temporality) MemoryRequired(mkind sdkapi.InstrumentKind) bool {
+	switch mkind {
+	case sdkapi.HistogramInstrumentKind, sdkapi.GaugeObserverInstrumentKind,
+		sdkapi.CounterInstrumentKind, sdkapi.UpDownCounterInstrumentKind:
+		// Delta-oriented instruments:
+		return t.Includes(CumulativeTemporality)
+
+	case sdkapi.CounterObserverInstrumentKind, sdkapi.UpDownCounterObserverInstrumentKind:
+		// Cumulative-oriented instruments:
+		return t.Includes(DeltaTemporality)
+	}
+	// Something unexpected is happening--we could panic.  This
+	// will become an error when the exporter tries to access a
+	// checkpoint, presumably, so let it be.
+	return false
+}
+
+type (
+	constantTemporalitySelector  Temporality
+	statelessTemporalitySelector struct{}
+)
+
+var (
+	_ TemporalitySelector = constantTemporalitySelector(0)
+	_ TemporalitySelector = statelessTemporalitySelector{}
+)
+
+// ConstantTemporalitySelector returns an TemporalitySelector that returns
+// a constant Temporality.
+func ConstantTemporalitySelector(t Temporality) TemporalitySelector {
+	return constantTemporalitySelector(t)
+}
+
+// CumulativeTemporalitySelector returns an TemporalitySelector that
+// always returns CumulativeTemporality.
+func CumulativeTemporalitySelector() TemporalitySelector {
+	return ConstantTemporalitySelector(CumulativeTemporality)
+}
+
+// DeltaTemporalitySelector returns an TemporalitySelector that
+// always returns DeltaTemporality.
+func DeltaTemporalitySelector() TemporalitySelector {
+	return ConstantTemporalitySelector(DeltaTemporality)
+}
+
+// StatelessTemporalitySelector returns an TemporalitySelector that
+// always returns the Temporality that avoids long-term memory
+// requirements.
+func StatelessTemporalitySelector() TemporalitySelector {
+	return statelessTemporalitySelector{}
+}
+
+// TemporalityFor implements TemporalitySelector.
+func (c constantTemporalitySelector) TemporalityFor(_ *sdkapi.Descriptor, _ Kind) Temporality {
+	return Temporality(c)
+}
+
+// TemporalityFor implements TemporalitySelector.
+func (s statelessTemporalitySelector) TemporalityFor(desc *sdkapi.Descriptor, kind Kind) Temporality {
+	if kind == SumKind && desc.InstrumentKind().PrecomputedSum() {
+		return CumulativeTemporality
+	}
+	return DeltaTemporality
+}
+
+// TemporalitySelector is a sub-interface of Exporter used to indicate
+// whether the Processor should compute Delta or Cumulative
+// Aggregations.
+type TemporalitySelector interface {
+	// TemporalityFor should return the correct Temporality that
+	// should be used when exporting data for the given metric
+	// instrument and Aggregator kind.
+	TemporalityFor(descriptor *sdkapi.Descriptor, aggregationKind Kind) Temporality
+}

vendor/go.opentelemetry.io/otel/sdk/export/metric/aggregation/temporality_string.go

@@ -0,0 +1,25 @@
+// Code generated by "stringer -type=Temporality"; DO NOT EDIT.
+
+package aggregation
+
+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[CumulativeTemporality-1]
+	_ = x[DeltaTemporality-2]
+}
+
+const _Temporality_name = "CumulativeTemporalityDeltaTemporality"
+
+var _Temporality_index = [...]uint8{0, 21, 37}
+
+func (i Temporality) String() string {
+	i -= 1
+	if i >= Temporality(len(_Temporality_index)-1) {
+		return "Temporality(" + strconv.FormatInt(int64(i+1), 10) + ")"
+	}
+	return _Temporality_name[_Temporality_index[i]:_Temporality_index[i+1]]
+}