Native Histogram Builder

Builds a serialized native histogram payload with configurable positive and negative bucket spans, supporting either delta-based or absolute bucket populations.

Capabilities

Maps spans to payload

• Creating a histogram with schema 5, zero count 2.5, negative spans [{offset: -3, length: 2}], and positive spans [{offset: 0, length: 3}] yields a payload whose span descriptors match the provided offsets/lengths on both sides, aligns bucket slots to the provided spans, and preserves the schema and timestamp in the encoded result. @test

Encodes delta populations

• With UseDelta true and bucket deltas negative=[1, 2], positive=[3, 1], the payload encodes bucket populations using the delta representation for each sign, leaves absolute-count fields empty, and sets the total sample count to the sum of zero bucket plus the provided deltas in span order. @test

Encodes absolute populations

• With UseDelta false, zero count 0.25, and bucket populations negative=[1.5], positive=[2.0, 0.5], the payload encodes absolute bucket counts (including fractional values) for both signs, leaves delta fields empty, and sets the total sample count to the sum of zero bucket plus the provided absolute counts. @test

Implementation

@generates

API

type BucketSpan struct {
    Offset int32
    Length int32
}

type BucketPopulation struct {
    Negative []float64
    Positive []float64
    UseDelta bool
}

type NativeHistogramSpec struct {
    Schema     int32
    ZeroCount  float64
    NegativeSpans []BucketSpan
    PositiveSpans []BucketSpan
    Buckets    BucketPopulation
    TimestampMs int64
}

// BuildNativeHistogram constructs a native histogram payload using the provided spans and bucket populations.
// When UseDelta is true, bucket values represent per-bucket deltas; otherwise they are absolute counts that may include fractional values.
// The returned bytes must encode the histogram in the dependency's native histogram format, selecting delta or absolute bucket representation based on UseDelta.
func BuildNativeHistogram(spec NativeHistogramSpec) ([]byte, error)

Dependencies { .dependencies }

prometheus-client-model { .dependency }

Defines the native histogram metric schema used for serialization. @satisfied-by