Gauge Histogram Snapshot Builder

Builds a serialized gauge histogram metric payload from bucketed observations while retaining histogram-style bucket encoding.

Capabilities

Compose gauge histogram payload

• Given inputs with name request_latency, sample count 6, sample sum 12.5, zero count 1, positive span offset 0 width 2 and bucket deltas [2, 3], and a negative span offset -2 width 1 with delta [1], the emitted bytes decode to a metric flagged as gauge histogram that uses a histogram payload containing zero bucket count, positive cumulative counts [2, 5], negative cumulative counts [1], and the provided sum and count. @test

Honor float counts

• When sample count 5.5 and zero count 1.2 are provided, the payload encodes those float counters instead of integer counters while preserving gauge histogram type and bucket populations. @test

Attach exemplars

• When an exemplar with timestamp 1700000000000, value 0.34, and labels {"trace_id": "abcd"} is attached to the first positive bucket, the emitted payload keeps the gauge histogram type and includes that exemplar on the matching bucket entry. @test

Bucket populations use Deltas as integer increments per span bucket; when Counts are supplied, treat them as absolute float counts aligned to the same bucket order.

Implementation

@generates

API

type BucketSpan struct {
  Offset int32
  Width uint32
  Deltas []int64
  Counts []float64
  Exemplar *Exemplar
}

type Exemplar struct {
  Value float64
  TimestampMs int64
  Labels map[string]string
}

type GaugeHistogramInput struct {
  Name string
  Help string
  Unit string
  Positive BucketSpan
  Negative BucketSpan
  ZeroCount float64
  SampleCount float64
  SampleSum float64
}

func BuildGaugeHistogramPayload(input GaugeHistogramInput) ([]byte, error)

Dependencies { .dependencies }

prometheus-client-model { .dependency }

Provides Prometheus metric protobuf definitions for gauge histograms built on the histogram payload.

@satisfied-by