expo

Documentation

Overview

Package expo implements various operations on exponential histograms and their bucket counts

Index

• func Collapse(bs Buckets)
• func Downscale(bs Buckets, from, to Scale)
• func HiLo[T any, N cmp.Ordered](a, b T, fn func(T) N) (hi, lo T)
• func Merge(arel, brel Buckets)
• func WidenZero(dp DataPoint, width float64)
• type Absolute
  • func Abs(bs Buckets) Absolute
  • func (a Absolute) Abs(at int) uint64
  • func (a Absolute) Lower() int
  • func (a Absolute) Slice(from, to int)
  • func (a Absolute) Upper() int
• type Buckets
• type DataPoint
• type Scale
  • func (scale Scale) Bounds(index int) (min, max float64)
  • func (scale Scale) Idx(v float64) int

Examples

• Absolute

Functions

func Collapse

func Collapse(bs Buckets)

Collapse merges adjacent buckets and zeros the remaining area:

before:	1 1 1 1 1 1 1 1 1 1 1 1
after:	 2   2   2   2   2   2   0   0   0   0   0   0

Due to the "perfect subsetting" property of exponential histograms, this gives the same observation as before, but recorded at scale-1. See https://opentelemetry.io/docs/specs/otel/metrics/data-model/#exponential-scale.

Because every bucket now spans twice as much range, half of the allocated counts slice is technically no longer required. It is zeroed but left in place to avoid future allocations, because observations may happen in that area at a later time.

func Downscale

func Downscale(bs Buckets, from, to Scale)

Downscale collapses the buckets of bs until scale 'to' is reached

func HiLo

func HiLo[T any, N cmp.Ordered](a, b T, fn func(T) N) (hi, lo T)

HiLo returns the greater of a and b by comparing the result of applying fn to each. If equal, returns operands as passed

func Merge

func Merge(arel, brel Buckets)

Merge combines the counts of buckets a and b into a. Both buckets MUST be of same scale

func WidenZero

func WidenZero(dp DataPoint, width float64)

WidenZero widens the zero-bucket to span at least [-width,width], possibly wider if min falls in the middle of a bucket.

Both buckets counts MUST be of same scale.

Types

type Absolute

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

Absolute addresses bucket counts using an absolute scale, such that it is interoperable with Scale.

It spans from [Absolute.Lower:Absolute.Upper]

NOTE: The zero-value is unusable, use Abs to construct

Example

package main

import (
	"fmt"

	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/deltatocumulativeprocessor/internal/data/expo"
	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/deltatocumulativeprocessor/internal/data/expo/expotest"
)

func main() {
	nums := []float64{0.4, 2.3, 2.4, 4.5}

	bs := expotest.Observe0(nums...)
	abs := expo.Abs(bs)

	s := expo.Scale(0)
	for _, n := range nums {
		fmt.Printf("%.1f belongs to bucket %+d\n", n, s.Idx(n))
	}

	fmt.Printf("\n index:")
	for i := 0; i < bs.BucketCounts().Len(); i++ {
		fmt.Printf("  %d", i)
	}
	fmt.Printf("\n   abs:")
	for i := abs.Lower(); i < abs.Upper(); i++ {
		fmt.Printf(" %+d", i)
	}
	fmt.Printf("\ncounts:")
	for i := abs.Lower(); i < abs.Upper(); i++ {
		fmt.Printf("  %d", abs.Abs(i))
	}

}

Output:

0.4 belongs to bucket -2
2.3 belongs to bucket +1
2.4 belongs to bucket +1
4.5 belongs to bucket +2

 index:  0  1  2  3  4
   abs: -2 -1 +0 +1 +2
counts:  1  0  0  2  1

func Abs

func Abs(bs Buckets) Absolute

Abs returns a view into the buckets using an absolute scale

func (Absolute) Abs

func (a Absolute) Abs(at int) uint64

Abs returns the value at absolute index 'at'

func (Absolute) Lower

func (a Absolute) Lower() int

Lower returns the minimal index inside the set, such that every i >= Lower

func (Absolute) Slice

func (a Absolute) Slice(from, to int)

Slice drops data outside the range from <= i < to from the bucket counts. It behaves the same as Go's [a:b]

Limitations:

• due to a limitation of the pcommon package, slicing cannot happen in-place and allocates
• in consequence, data outside the range is garbage collected

func (Absolute) Upper

func (a Absolute) Upper() int

Upper returns the minimal index outside the set, such that every i < Upper

type Buckets

type Buckets = pmetric.ExponentialHistogramDataPointBuckets

type DataPoint

type DataPoint = pmetric.ExponentialHistogramDataPoint

type Scale

type Scale int32

func (Scale) Bounds

func (scale Scale) Bounds(index int) (min, max float64)

Bounds returns the half-open interval (min,max] of the bucket at index. This means a value min < v <= max belongs to this bucket.

NOTE: this is different from Go slice intervals, which are [a,b)

func (Scale) Idx

func (scale Scale) Idx(v float64) int

Idx gives the bucket index v belongs into