Handle more arithmetic operators for native histograms

docs/querying/functions.md

@@ -589,8 +589,9 @@ over time and return an instant vector with per-series aggregation results:
 Note that all values in the specified interval have the same weight in the
 aggregation even if the values are not equally spaced throughout the interval.
 
-`count_over_time`, `last_over_time`, and `present_over_time` handle native
-histograms as expected. All other functions ignore histogram samples.
+`avg_over_time`, `sum_over_time`, `count_over_time`, `last_over_time`, and
+`present_over_time` handle native histograms as expected. All other functions
+ignore histogram samples.
 
 ## Trigonometric Functions
 

docs/querying/operators.md

@@ -318,19 +318,23 @@ histograms is still very limited.
 Logical/set binary operators work as expected even if histogram samples are
 involved. They only check for the existence of a vector element and don't
 change their behavior depending on the sample type of an element (float or
-histogram).
+histogram). The `count` aggregation operator works similarly.
 
-The binary `+` operator between two native histograms and the `sum` aggregation
-operator to aggregate native histograms are fully supported. Even if the
-histograms involved have different bucket layouts, the buckets are
-automatically converted appropriately so that the operation can be
+The binary `+` and `-` operators between two native histograms and the `sum`
+and `avg` aggregation operators to aggregate native histograms are fully
+supported. Even if the histograms involved have different bucket layouts, the
+buckets are automatically converted appropriately so that the operation can be
 performed. (With the currently supported bucket schemas, that's always
-possible.) If either operator has to sum up a mix of histogram samples and
+possible.) If either operator has to aggregate a mix of histogram samples and
 float samples, the corresponding vector element is removed from the output
 vector entirely.
 
-All other operators do not behave in a meaningful way. They either treat the
-histogram sample as if it were a float sample of value 0, or (in case of
-arithmetic operations between a scalar and a vector) they leave the histogram
-sample unchanged. This behavior will change to a meaningful one before native
-histograms are a stable feature.
+The binary `*` operator works between a native histogram and a float in any
+order, while the binary `/` operator can be used between a native histogram
+and a float in that exact order.
+
+All other operators (and unmentioned cases for the above operators) do not
+behave in a meaningful way. They either treat the histogram sample as if it
+were a float sample of value 0, or (in case of arithmetic operations between a
+scalar and a vector) they leave the histogram sample unchanged. This behavior
+will change to a meaningful one before native histograms are a stable feature.

model/histogram/float_histogram.go

@@ -159,12 +159,12 @@ func (h *FloatHistogram) ZeroBucket() Bucket[float64] {
 	}
 }
 
-// Scale scales the FloatHistogram by the provided factor, i.e. it scales all
+// Mul multiplies the FloatHistogram by the provided factor, i.e. it scales all
 // bucket counts including the zero bucket and the count and the sum of
 // observations. The bucket layout stays the same. This method changes the
 // receiving histogram directly (rather than acting on a copy). It returns a
 // pointer to the receiving histogram for convenience.
-func (h *FloatHistogram) Scale(factor float64) *FloatHistogram {
+func (h *FloatHistogram) Mul(factor float64) *FloatHistogram {
 	h.ZeroCount *= factor
 	h.Count *= factor
 	h.Sum *= factor
@@ -177,6 +177,21 @@ func (h *FloatHistogram) Scale(factor float64) *FloatHistogram {
 	return h
 }
 
+// Div works like Scale but divides instead of multiplies.
+// When dividing by 0, everything will be set to Inf.
+func (h *FloatHistogram) Div(scalar float64) *FloatHistogram {
+	h.ZeroCount /= scalar
+	h.Count /= scalar
+	h.Sum /= scalar
+	for i := range h.PositiveBuckets {
+		h.PositiveBuckets[i] /= scalar
+	}
+	for i := range h.NegativeBuckets {
+		h.NegativeBuckets[i] /= scalar
+	}
+	return h
+}
+
 // Add adds the provided other histogram to the receiving histogram. Count, Sum,
 // and buckets from the other histogram are added to the corresponding
 // components of the receiving histogram. Buckets in the other histogram that do

model/histogram/float_histogram_test.go

@@ -15,12 +15,13 @@ package histogram
 
 import (
 	"fmt"
+	"math"
 	"testing"
 
 	"github.com/stretchr/testify/require"
 )
 
-func TestFloatHistogramScale(t *testing.T) {
+func TestFloatHistogramMul(t *testing.T) {
 	cases := []struct {
 		name     string
 		in       *FloatHistogram
@@ -33,6 +34,30 @@ func TestFloatHistogramScale(t *testing.T) {
 			3.1415,
 			&FloatHistogram{},
 		},
+		{
+			"zero multiplier",
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       5.5,
+				Count:           3493.3,
+				Sum:             2349209.324,
+				PositiveSpans:   []Span{{-2, 1}, {2, 3}},
+				PositiveBuckets: []float64{1, 3.3, 4.2, 0.1},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{3.1, 3, 1.234e5, 1000},
+			},
+			0,
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       0,
+				Count:           0,
+				Sum:             0,
+				PositiveSpans:   []Span{{-2, 1}, {2, 3}},
+				PositiveBuckets: []float64{0, 0, 0, 0},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{0, 0, 0, 0},
+			},
+		},
 		{
 			"no-op",
 			&FloatHistogram{
@@ -81,17 +106,137 @@ func TestFloatHistogramScale(t *testing.T) {
 				NegativeBuckets: []float64{6.2, 6, 1.234e5 * 2, 2000},
 			},
 		},
+		{
+			"triple",
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       11,
+				Count:           30,
+				Sum:             23,
+				PositiveSpans:   []Span{{-2, 2}, {1, 3}},
+				PositiveBuckets: []float64{1, 0, 3, 4, 7},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{3, 1, 5, 6},
+			},
+			3,
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       33,
+				Count:           90,
+				Sum:             69,
+				PositiveSpans:   []Span{{-2, 2}, {1, 3}},
+				PositiveBuckets: []float64{3, 0, 9, 12, 21},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{9, 3, 15, 18},
+			},
+		},
 	}
 
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
-			require.Equal(t, c.expected, c.in.Scale(c.scale))
+			require.Equal(t, c.expected, c.in.Mul(c.scale))
 			// Has it also happened in-place?
 			require.Equal(t, c.expected, c.in)
 		})
 	}
 }
 
+func TestFloatHistogramDiv(t *testing.T) {
+	cases := []struct {
+		name     string
+		fh       *FloatHistogram
+		s        float64
+		expected *FloatHistogram
+	}{
+		{
+			"zero value",
+			&FloatHistogram{},
+			3.1415,
+			&FloatHistogram{},
+		},
+		{
+			"zero divisor",
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       5.5,
+				Count:           3493.3,
+				Sum:             2349209.324,
+				PositiveSpans:   []Span{{-2, 1}, {2, 3}},
+				PositiveBuckets: []float64{1, 3.3, 4.2, 0.1},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{3.1, 3, 1.234e5, 1000},
+			},
+			0,
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       math.Inf(1),
+				Count:           math.Inf(1),
+				Sum:             math.Inf(1),
+				PositiveSpans:   []Span{{-2, 1}, {2, 3}},
+				PositiveBuckets: []float64{math.Inf(1), math.Inf(1), math.Inf(1), math.Inf(1)},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{math.Inf(1), math.Inf(1), math.Inf(1), math.Inf(1)},
+			},
+		},
+		{
+			"no-op",
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       5.5,
+				Count:           3493.3,
+				Sum:             2349209.324,
+				PositiveSpans:   []Span{{-2, 1}, {2, 3}},
+				PositiveBuckets: []float64{1, 3.3, 4.2, 0.1},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{3.1, 3, 1.234e5, 1000},
+			},
+			1,
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       5.5,
+				Count:           3493.3,
+				Sum:             2349209.324,
+				PositiveSpans:   []Span{{-2, 1}, {2, 3}},
+				PositiveBuckets: []float64{1, 3.3, 4.2, 0.1},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{3.1, 3, 1.234e5, 1000},
+			},
+		},
+		{
+			"half",
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       11,
+				Count:           30,
+				Sum:             23,
+				PositiveSpans:   []Span{{-2, 2}, {1, 3}},
+				PositiveBuckets: []float64{1, 0, 3, 4, 7},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{3, 1, 5, 6},
+			},
+			2,
+			&FloatHistogram{
+				ZeroThreshold:   0.01,
+				ZeroCount:       5.5,
+				Count:           15,
+				Sum:             11.5,
+				PositiveSpans:   []Span{{-2, 2}, {1, 3}},
+				PositiveBuckets: []float64{0.5, 0, 1.5, 2, 3.5},
+				NegativeSpans:   []Span{{3, 2}, {3, 2}},
+				NegativeBuckets: []float64{1.5, 0.5, 2.5, 3},
+			},
+		},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			require.Equal(t, c.expected, c.fh.Div(c.s))
+			// Has it also happened in-place?
+			require.Equal(t, c.expected, c.fh)
+		})
+	}
+}
+
 func TestFloatHistogramDetectReset(t *testing.T) {
 	cases := []struct {
 		name              string