1// Copyright The OpenTelemetry Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//go:generate stringer -type=Temporality
16
17package aggregation // import "go.opentelemetry.io/otel/sdk/export/metric/aggregation"
18
19import (
20	"go.opentelemetry.io/otel/metric/sdkapi"
21)
22
23// Temporality indicates the temporal aggregation exported by an exporter.
24// These bits may be OR-d together when multiple exporters are in use.
25type Temporality uint8
26
27const (
28	// CumulativeTemporality indicates that an Exporter expects a
29	// Cumulative Aggregation.
30	CumulativeTemporality Temporality = 1
31
32	// DeltaTemporality indicates that an Exporter expects a
33	// Delta Aggregation.
34	DeltaTemporality Temporality = 2
35)
36
37// Includes returns if t includes support for other temporality.
38func (t Temporality) Includes(other Temporality) bool {
39	return t&other != 0
40}
41
42// MemoryRequired returns whether an exporter of this temporality requires
43// memory to export correctly.
44func (t Temporality) MemoryRequired(mkind sdkapi.InstrumentKind) bool {
45	switch mkind {
46	case sdkapi.HistogramInstrumentKind, sdkapi.GaugeObserverInstrumentKind,
47		sdkapi.CounterInstrumentKind, sdkapi.UpDownCounterInstrumentKind:
48		// Delta-oriented instruments:
49		return t.Includes(CumulativeTemporality)
50
51	case sdkapi.CounterObserverInstrumentKind, sdkapi.UpDownCounterObserverInstrumentKind:
52		// Cumulative-oriented instruments:
53		return t.Includes(DeltaTemporality)
54	}
55	// Something unexpected is happening--we could panic.  This
56	// will become an error when the exporter tries to access a
57	// checkpoint, presumably, so let it be.
58	return false
59}
60
61type (
62	constantTemporalitySelector  Temporality
63	statelessTemporalitySelector struct{}
64)
65
66var (
67	_ TemporalitySelector = constantTemporalitySelector(0)
68	_ TemporalitySelector = statelessTemporalitySelector{}
69)
70
71// ConstantTemporalitySelector returns an TemporalitySelector that returns
72// a constant Temporality.
73func ConstantTemporalitySelector(t Temporality) TemporalitySelector {
74	return constantTemporalitySelector(t)
75}
76
77// CumulativeTemporalitySelector returns an TemporalitySelector that
78// always returns CumulativeTemporality.
79func CumulativeTemporalitySelector() TemporalitySelector {
80	return ConstantTemporalitySelector(CumulativeTemporality)
81}
82
83// DeltaTemporalitySelector returns an TemporalitySelector that
84// always returns DeltaTemporality.
85func DeltaTemporalitySelector() TemporalitySelector {
86	return ConstantTemporalitySelector(DeltaTemporality)
87}
88
89// StatelessTemporalitySelector returns an TemporalitySelector that
90// always returns the Temporality that avoids long-term memory
91// requirements.
92func StatelessTemporalitySelector() TemporalitySelector {
93	return statelessTemporalitySelector{}
94}
95
96// TemporalityFor implements TemporalitySelector.
97func (c constantTemporalitySelector) TemporalityFor(_ *sdkapi.Descriptor, _ Kind) Temporality {
98	return Temporality(c)
99}
100
101// TemporalityFor implements TemporalitySelector.
102func (s statelessTemporalitySelector) TemporalityFor(desc *sdkapi.Descriptor, kind Kind) Temporality {
103	if kind == SumKind && desc.InstrumentKind().PrecomputedSum() {
104		return CumulativeTemporality
105	}
106	return DeltaTemporality
107}
108
109// TemporalitySelector is a sub-interface of Exporter used to indicate
110// whether the Processor should compute Delta or Cumulative
111// Aggregations.
112type TemporalitySelector interface {
113	// TemporalityFor should return the correct Temporality that
114	// should be used when exporting data for the given metric
115	// instrument and Aggregator kind.
116	TemporalityFor(descriptor *sdkapi.Descriptor, aggregationKind Kind) Temporality
117}
118