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 ¶

• type Exemplar
• type Reservoir
• func Drop() Reservoir
• func FixedSize(k int) Reservoir
• func Histogram(bounds []float64) Reservoir
• func SampledFilter(r Reservoir) 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

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 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 Drop ¶

func Drop() Reservoir

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

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.

func SampledFilter ¶

func SampledFilter(r Reservoir) Reservoir

SampledFilter returns a Reservoir wrapping r that will only offer measurements to r if the passed context associated with the measurement contains a sampled go.opentelemetry.io/otel/trace.SpanContext.

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 hist.go rand.go reservoir.go storage.go value.go