aggregator

Documentation

Overview

package aggregator defines the interface used between the SDK and various kinds of aggregation.

Note, about the use of Go-1.18 generics! This code makes use of a pattern that gives the SDK fine control over memory layout via the use of a `Storage any` type constraint. The SDK is expected to pair the allocated `Storage any` value with corresponding `Methods` type, which provides pointer-receiver methods that operate on one or two `Storage` objects.

This means there are places where a Storage object appears as an generic type with no constraints. Where that happens without the corresponding Methods, it means the Storage is opaque at that level in the code.

Index

• Variables
• func RangeTest[N number.Any, Traits number.Traits[N]](num N, desc sdkinstrument.Descriptor) bool
• type Config
  • func (c Config) Valid() bool
  • func (c Config) Validate() (Config, error)
• type ConfigSelector
• type JSONConfig
• type JSONHistogramConfig
• type Methods

Variables

var (
	ErrNegativeInput = fmt.Errorf("negative value is out of range for this instrument")
	ErrNaNInput      = fmt.Errorf("NaN value is an invalid input")
	ErrInfInput      = fmt.Errorf("±Inf value is an invalid input")
)

Sentinel errors for Aggregator interface.

Functions

func RangeTest

func RangeTest[N number.Any, Traits number.Traits[N]](num N, desc sdkinstrument.Descriptor) bool

RangeTest is a common routine for testing for valid input values. This rejects NaN and Inf values. This rejects negative values when the aggregation does not support negative values, including monotonic counter metrics and Histogram metrics.

Types

type Config

type Config struct {
	// Histogram configuration, specifically.
	Histogram histostruct.Config

	// CardinalityLimit limits the number of instances of this
	// aggregator in a given view.
	CardinalityLimit uint32
}

Config supports the configuration for all aggregators in a single struct.

func (Config) Valid

func (c Config) Valid() bool

Valid returns true for valid configurations.

func (Config) Validate

func (c Config) Validate() (Config, error)

Valid returns a valid Configuration along with an error if there were invalid settings. Note that the empty state is considered valid and a correct

type ConfigSelector

type ConfigSelector func(sdkinstrument.Kind) (int64Config, float64Config Config)

ConfigSelector is a per-instrument-kind, per-number-kind Config choice.

type JSONConfig

type JSONConfig struct {
	Histogram        JSONHistogramConfig `json:"histogram"`
	CardinalityLimit uint32              `json:"cardinality_limit"`
}

JSONConfig supports the configuration for all aggregators in a single struct.

type JSONHistogramConfig

type JSONHistogramConfig struct {
	MaxSize int32 `json:"max_size"`
}

JSONHistogramConfig configures the exponential histogram.

type Methods

type Methods[N number.Any, Storage any] interface {
	// Init initializes the storage.
	Init(ptr *Storage, cfg Config)

	// Update modifies Storage concurrently with respect to
	// concurrent Move(), Copy(), and Update() operations.
	Update(ptr *Storage, number N)

	// Move atomically copies `input` to `output` and resets
	// `input` to the zero state.  The change to `input` is
	// synchronized against concurrent `Update()` and `Merge()`
	// operations.  The change to `output` is not synchronized.
	Move(input, output *Storage)

	// Merge adds the contents of `input` to `output`.  The read
	// of `input` is not synchronized.  The write to `output` is
	// synchronized with concurrent `Merge()` calls (writing) and
	// concurrent `Copy()` or `Move()` calls (reading).
	Merge(input, output *Storage)

	// Copy replaces the contents of `output` with the contents of
	// `input`, which is unmodified.  The read from `input` is
	// synchronized with concurrent `Merge()` and `Update()` calls.
	Copy(input, output *Storage)

	// SubtractSwap performs `*operand = *argument - *operand`
	// with no synchronization.  We are not concerned with
	// synchronization because this is only used for asynchronous
	// instruments.  To use SubtractSwap in a synchronous
	// scenario, use Copy() or Move() first.
	SubtractSwap(operand, argument *Storage)

	// ToAggregation returns an exporter-ready value.
	ToAggregation(ptr *Storage) aggregation.Aggregation

	// ToStorage returns the underlying storage of an existing Aggregation.
	ToStorage(aggregation.Aggregation) (*Storage, bool)

	// Kind returns the Kind of aggregator.
	Kind() aggregation.Kind

	// HasChange returns true if there have been any (discernible)
	// Updates.  This tests whether an aggregation has zero sum,
	// zero count, or zero difference, depending on the
	// aggregation.  If the instrument is asynchronous, this will
	// be called after subtraction.  Not synchronized.
	HasChange(ptr *Storage) bool
}

Methods implements a specific aggregation behavior for a specific type of aggregator Storage. Methods are parameterized by the type of the number (int64, float64), the Storage (generally a `Storage` struct in the same package as the corresponding Methods).

Methods have four methods that mutate the Storage. In every case, one of the Storage is synchronized against the other operations. The synchronized methods are:

Update: Modifies one Storage (synchronized). Move: Reads-and-resets one Storage (synchronized), writes one Storage. Copy: Reads one Storage (synchronized), writes one Storage. Merge: Reads one Storage, writes one Storeage (synchronized).

Generally, the sequence of operations from observation to export is different for synchronous and asynchronous instruments. For synchronous instruments:

1. Update() from an API method call into the accumulator's current Storage 2. Move() from the accumulator's storage into the accumulator's snapshot Storage 3. Merge() from the snapshot Storage to the output Storage. 4. Copy() or Move() from the output Storage to the exported data.

Note that these methods are responsible for synchronization between steps (1 vs 2) and (3 vs 4). The accumulator uses its own lock to protect the snapshot Storage between steps 2 and 3.