package exemplar

import "go.opentelemetry.io/otel/sdk/metric/internal/exemplar"

Package exemplar provides an implementation of the OpenTelemetry exemplar reservoir to be used in metric collection pipelines.

Index ¶

• func AlwaysOnFilter(ctx context.Context) bool
• func SampledFilter(ctx context.Context) bool
• type Exemplar
• type Filter
• type FilteredReservoir
• func Drop[N int64 | float64]() FilteredReservoir[N]
• func NewFilteredReservoir[N int64 | float64](f Filter, r Reservoir) FilteredReservoir[N]
• type Reservoir
• func FixedSize(k int) Reservoir
• func Histogram(bounds []float64) Reservoir
• type Value
• func NewValue[N int64 | float64](value N) Value
• func (v Value) Float64() float64
• func (v Value) Int64() int64
• func (v Value) Type() ValueType
• type ValueType

Functions ¶

func AlwaysOnFilter ¶

func AlwaysOnFilter(ctx context.Context) bool

AlwaysOnFilter is a Filter that always offers measurements.

func SampledFilter ¶

func SampledFilter(ctx context.Context) bool

SampledFilter is a Filter that will only offer measurements if the passed context associated with the measurement contains a sampled go.opentelemetry.io/otel/trace.SpanContext.

Types ¶

type Exemplar ¶

type Exemplar struct {
	// FilteredAttributes are the attributes recorded with the measurement but
	// filtered out of the timeseries' aggregated data.
	FilteredAttributes []attribute.KeyValue
	// Time is the time when the measurement was recorded.
	Time time.Time
	// Value is the measured value.
	Value Value
	// SpanID is the ID of the span that was active during the measurement. If
	// no span was active or the span was not sampled this will be empty.
	SpanID []byte `json:",omitempty"`
	// TraceID is the ID of the trace the active span belonged to during the
	// measurement. If no span was active or the span was not sampled this will
	// be empty.
	TraceID []byte `json:",omitempty"`
}

Exemplar is a measurement sampled from a timeseries providing a typical example.

type Filter ¶

type Filter func(context.Context) bool

Filter determines if a measurement should be offered.

The passed ctx needs to contain any baggage or span that were active when the measurement was made. This information may be used by the Reservoir in making a sampling decision.

type FilteredReservoir ¶

type FilteredReservoir[N int64 | float64] interface {
	// Offer accepts the parameters associated with a measurement. The
	// parameters will be stored as an exemplar if the filter decides to
	// sample the measurement.
	//
	// The passed ctx needs to contain any baggage or span that were active
	// when the measurement was made. This information may be used by the
	// Reservoir in making a sampling decision.
	Offer(ctx context.Context, val N, attr []attribute.KeyValue)
	// Collect returns all the held exemplars in the reservoir.
	Collect(dest *[]Exemplar)
}

FilteredReservoir wraps a Reservoir with a filter.

func Drop ¶

func Drop[N int64 | float64]() FilteredReservoir[N]

Drop returns a FilteredReservoir that drops all measurements it is offered.

func NewFilteredReservoir ¶

func NewFilteredReservoir[N int64 | float64](f Filter, r Reservoir) FilteredReservoir[N]

NewFilteredReservoir creates a FilteredReservoir which only offers values that are allowed by the filter.

type Reservoir ¶

type Reservoir interface {
	// Offer accepts the parameters associated with a measurement. The
	// parameters will be stored as an exemplar if the Reservoir decides to
	// sample the measurement.
	//
	// The passed ctx needs to contain any baggage or span that were active
	// when the measurement was made. This information may be used by the
	// Reservoir in making a sampling decision.
	//
	// The time t is the time when the measurement was made. The val and attr
	// parameters are the value and dropped (filtered) attributes of the
	// measurement respectively.
	Offer(ctx context.Context, t time.Time, val Value, attr []attribute.KeyValue)

	// Collect returns all the held exemplars.
	//
	// The Reservoir state is preserved after this call.
	Collect(dest *[]Exemplar)
}

Reservoir holds the sampled exemplar of measurements made.

func FixedSize ¶

func FixedSize(k int) Reservoir

FixedSize returns a Reservoir that samples at most k exemplars. If there are k or less measurements made, the Reservoir will sample each one. If there are more than k, the Reservoir will then randomly sample all additional measurement with a decreasing probability.

func Histogram ¶

func Histogram(bounds []float64) Reservoir

Histogram returns a Reservoir that samples the last measurement that falls within a histogram bucket. The histogram bucket upper-boundaries are define by bounds.

The passed bounds will be sorted by this function.

type Value ¶

type Value struct {
	// contains filtered or unexported fields
}

Value is the value of data held by an exemplar.

func NewValue ¶

func NewValue[N int64 | float64](value N) Value

NewValue returns a new Value for the provided value.

func (Value) Float64 ¶

func (v Value) Float64() float64

Float64 returns the value of v as an float64. If the ValueType of v is not an Float64ValueType, 0 is returned.

func (Value) Int64 ¶

func (v Value) Int64() int64

Int64 returns the value of v as an int64. If the ValueType of v is not an Int64ValueType, 0 is returned.

func (Value) Type ¶

func (v Value) Type() ValueType

Type returns the ValueType of data held by v.

type ValueType ¶

type ValueType uint8

ValueType identifies the type of value used in exemplar data.

const (
	// UnknownValueType should not be used. It represents a misconfigured
	// Value.
	UnknownValueType ValueType = 0
	// Int64ValueType represents a Value with int64 data.
	Int64ValueType ValueType = 1
	// Float64ValueType represents a Value with float64 data.
	Float64ValueType ValueType = 2
)

Source Files ¶

doc.go drop.go exemplar.go filter.go filtered_reservoir.go hist.go rand.go reservoir.go storage.go value.go