internal

Documentation

Overview

Package internal provides types and functionality used to aggregate and cycle the state of metric measurements made by the SDK. These types and functionality are meant only for internal SDK use.

Example

package main

import (
	"context"
	"fmt"

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/metric"
	"go.opentelemetry.io/otel/metric/embedded"
	"go.opentelemetry.io/otel/sdk/metric/aggregation"
	"go.opentelemetry.io/otel/sdk/metric/metricdata"
)

type meter struct {
	// When a reader initiates a collection, the meter would collect
	// aggregations from each of these functions.
	aggregations []metricdata.Aggregation
}

func (p *meter) Int64Counter(string, ...metric.Int64CounterOption) (metric.Int64Counter, error) {
	// This is an example of how a meter would create an aggregator for a new
	// counter. At this point the provider would determine the aggregation and
	// temporality to used based on the Reader and View configuration. Assume
	// here these are determined to be a cumulative sum.

	aggregator := NewCumulativeSum[int64](true)
	count := inst{aggregateFunc: aggregator.Aggregate}

	p.aggregations = append(p.aggregations, aggregator.Aggregation())

	fmt.Printf("using %T aggregator for counter\n", aggregator)

	return count, nil
}

func (p *meter) Int64UpDownCounter(string, ...metric.Int64UpDownCounterOption) (metric.Int64UpDownCounter, error) {
	// This is an example of how a meter would create an aggregator for a new
	// up-down counter. At this point the provider would determine the
	// aggregation and temporality to used based on the Reader and View
	// configuration. Assume here these are determined to be a last-value
	// aggregation (the temporality does not affect the produced aggregations).

	aggregator := NewLastValue[int64]()
	upDownCount := inst{aggregateFunc: aggregator.Aggregate}

	p.aggregations = append(p.aggregations, aggregator.Aggregation())

	fmt.Printf("using %T aggregator for up-down counter\n", aggregator)

	return upDownCount, nil
}

func (p *meter) Int64Histogram(string, ...metric.Int64HistogramOption) (metric.Int64Histogram, error) {
	// This is an example of how a meter would create an aggregator for a new
	// histogram. At this point the provider would determine the aggregation
	// and temporality to used based on the Reader and View configuration.
	// Assume here these are determined to be a delta explicit-bucket
	// histogram.

	aggregator := NewDeltaHistogram[int64](aggregation.ExplicitBucketHistogram{
		Boundaries: []float64{0, 5, 10, 25, 50, 75, 100, 250, 500, 1000},
		NoMinMax:   false,
	})
	hist := inst{aggregateFunc: aggregator.Aggregate}

	p.aggregations = append(p.aggregations, aggregator.Aggregation())

	fmt.Printf("using %T aggregator for histogram\n", aggregator)

	return hist, nil
}

// inst is a generalized int64 synchronous counter, up-down counter, and
// histogram used for demonstration purposes only.
type inst struct {
	aggregateFunc func(int64, attribute.Set)

	embedded.Int64Counter
	embedded.Int64UpDownCounter
	embedded.Int64Histogram
}

func (inst) Add(context.Context, int64, ...metric.AddOption)       {}
func (inst) Record(context.Context, int64, ...metric.RecordOption) {}

func main() {
	m := meter{}

	_, _ = m.Int64Counter("counter example")
	_, _ = m.Int64UpDownCounter("up-down counter example")
	_, _ = m.Int64Histogram("histogram example")

}

Output:

using *internal.cumulativeSum[int64] aggregator for counter
using *internal.lastValue[int64] aggregator for up-down counter
using *internal.deltaHistogram[int64] aggregator for histogram

Index

• func ReuseSlice[T any](slice []T, n int) []T
• type Aggregator
  • func NewCumulativeHistogram[N int64 | float64](cfg aggregation.ExplicitBucketHistogram) Aggregator[N]
  • func NewCumulativeSum[N int64 | float64](monotonic bool) Aggregator[N]
  • func NewDeltaHistogram[N int64 | float64](cfg aggregation.ExplicitBucketHistogram) Aggregator[N]
  • func NewDeltaSum[N int64 | float64](monotonic bool) Aggregator[N]
  • func NewFilter[N int64 | float64](agg Aggregator[N], fn attribute.Filter) Aggregator[N]
  • func NewLastValue[N int64 | float64]() Aggregator[N]
  • func NewPrecomputedCumulativeSum[N int64 | float64](monotonic bool) Aggregator[N]
  • func NewPrecomputedDeltaSum[N int64 | float64](monotonic bool) Aggregator[N]

Examples

• Package

Functions

func ReuseSlice

func ReuseSlice[T any](slice []T, n int) []T

ReuseSlice returns a zeroed view of slice if its capacity is greater than or equal to n. Otherwise, it returns a new []T with capacity equal to n.

Types

type Aggregator

type Aggregator[N int64 | float64] interface {
	// Aggregate records the measurement, scoped by attr, and aggregates it
	// into an aggregation.
	Aggregate(measurement N, attr attribute.Set)

	// Aggregation returns an Aggregation, for all the aggregated
	// measurements made and ends an aggregation cycle.
	Aggregation() metricdata.Aggregation
}

Aggregator forms an aggregation from a collection of recorded measurements.

Aggregators need to be comparable so they can be de-duplicated by the SDK when it creates them for multiple views.

func NewCumulativeHistogram

func NewCumulativeHistogram[N int64 | float64](cfg aggregation.ExplicitBucketHistogram) Aggregator[N]

NewCumulativeHistogram returns an Aggregator that summarizes a set of measurements as an histogram. Each histogram is scoped by attributes.

Each aggregation cycle builds from the previous, the histogram counts are the bucketed counts of all values aggregated since the returned Aggregator was created.

func NewCumulativeSum

func NewCumulativeSum[N int64 | float64](monotonic bool) Aggregator[N]

NewCumulativeSum returns an Aggregator that summarizes a set of measurements as their arithmetic sum. Each sum is scoped by attributes and the aggregation cycle the measurements were made in.

The monotonic value is used to communicate the produced Aggregation is monotonic or not. The returned Aggregator does not make any guarantees this value is accurate. It is up to the caller to ensure it.

Each aggregation cycle is treated independently. When the returned Aggregator's Aggregation method is called it will reset all sums to zero.

func NewDeltaHistogram

func NewDeltaHistogram[N int64 | float64](cfg aggregation.ExplicitBucketHistogram) Aggregator[N]

NewDeltaHistogram returns an Aggregator that summarizes a set of measurements as an histogram. Each histogram is scoped by attributes and the aggregation cycle the measurements were made in.

Each aggregation cycle is treated independently. When the returned Aggregator's Aggregations method is called it will reset all histogram counts to zero.

func NewDeltaSum

func NewDeltaSum[N int64 | float64](monotonic bool) Aggregator[N]

NewDeltaSum returns an Aggregator that summarizes a set of measurements as their arithmetic sum. Each sum is scoped by attributes and the aggregation cycle the measurements were made in.

The monotonic value is used to communicate the produced Aggregation is monotonic or not. The returned Aggregator does not make any guarantees this value is accurate. It is up to the caller to ensure it.

Each aggregation cycle is treated independently. When the returned Aggregator's Aggregation method is called it will reset all sums to zero.

func NewFilter

func NewFilter[N int64 | float64](agg Aggregator[N], fn attribute.Filter) Aggregator[N]

NewFilter returns an Aggregator that wraps an agg with an attribute filtering function. Both pre-computed non-pre-computed Aggregators can be passed for agg. An appropriate Aggregator will be returned for the detected type.

func NewLastValue

func NewLastValue[N int64 | float64]() Aggregator[N]

NewLastValue returns an Aggregator that summarizes a set of measurements as the last one made.

func NewPrecomputedCumulativeSum

func NewPrecomputedCumulativeSum[N int64 | float64](monotonic bool) Aggregator[N]

NewPrecomputedCumulativeSum returns an Aggregator that summarizes a set of pre-computed sums. Each sum is scoped by attributes and the aggregation cycle the measurements were made in.

The monotonic value is used to communicate the produced Aggregation is monotonic or not. The returned Aggregator does not make any guarantees this value is accurate. It is up to the caller to ensure it.

The output Aggregation will report recorded values as cumulative temporality.

func NewPrecomputedDeltaSum

func NewPrecomputedDeltaSum[N int64 | float64](monotonic bool) Aggregator[N]

NewPrecomputedDeltaSum returns an Aggregator that summarizes a set of pre-computed sums. Each sum is scoped by attributes and the aggregation cycle the measurements were made in.

The monotonic value is used to communicate the produced Aggregation is monotonic or not. The returned Aggregator does not make any guarantees this value is accurate. It is up to the caller to ensure it.

The output Aggregation will report recorded values as delta temporality.