# Minimal valid case: an empty histogram.
load 5m
	empty_histogram	{{}}

eval instant at 5m empty_histogram
	{__name__="empty_histogram"} {{}}

eval instant at 5m histogram_count(empty_histogram)
	{} 0

eval instant at 5m histogram_sum(empty_histogram)
	{} 0

eval instant at 5m histogram_fraction(-Inf, +Inf, empty_histogram)
	{} NaN

eval instant at 5m histogram_fraction(0, 8, empty_histogram)
	{} NaN



# buckets:[1 2 1] means 1 observation in the 1st bucket, 2 observations in the 2nd and 1 observation in the 3rd (total 4).
load 5m
	single_histogram	{{schema:0 sum:5 count:4 buckets:[1 2 1]}}

# histogram_count extracts the count property from the histogram.
eval instant at 5m histogram_count(single_histogram)
	{} 4

# histogram_sum extracts the sum property from the histogram.
eval instant at 5m histogram_sum(single_histogram)
	{} 5

# We expect half of the values to fall in the range 1 < x <= 2.
eval instant at 5m histogram_fraction(1, 2, single_histogram)
	{} 0.5

# We expect all values to fall in the range 0 < x <= 8.
eval instant at 5m histogram_fraction(0, 8, single_histogram)
	{} 1

# Median is 1.5 due to linear estimation of the midpoint of the middle bucket, whose values are within range 1 < x <= 2.
eval instant at 5m histogram_quantile(0.5, single_histogram)
	{} 1.5



# Repeat the same histogram 10 times.
load 5m
	multi_histogram	{{schema:0 sum:5 count:4 buckets:[1 2 1]}}x10

eval instant at 5m histogram_count(multi_histogram)
	{} 4

eval instant at 5m histogram_sum(multi_histogram)
	{} 5

eval instant at 5m histogram_fraction(1, 2, multi_histogram)
	{} 0.5

eval instant at 5m histogram_quantile(0.5, multi_histogram)
	{} 1.5


# Each entry should look the same as the first.
eval instant at 50m histogram_count(multi_histogram)
	{} 4

eval instant at 50m histogram_sum(multi_histogram)
	{} 5

eval instant at 50m histogram_fraction(1, 2, multi_histogram)
	{} 0.5

eval instant at 50m histogram_quantile(0.5, multi_histogram)
	{} 1.5



# Accumulate the histogram addition for 10 iterations, offset is a bucket position where offset:0 is always the bucket
# with an upper limit of 1 and offset:1 is the bucket which follows to the right. Negative offsets represent bucket
# positions for upper limits <1 (tending toward zero), where offset:-1 is the bucket to the left of offset:0.
load 5m
	incr_histogram	{{schema:0 sum:4 count:4 buckets:[1 2 1]}}+{{sum:2 count:1 buckets:[1] offset:1}}x10

eval instant at 5m histogram_count(incr_histogram)
	{} 5

eval instant at 5m histogram_sum(incr_histogram)
	{} 6

# We expect 3/5ths of the values to fall in the range 1 < x <= 2.
eval instant at 5m histogram_fraction(1, 2, incr_histogram)
	{} 0.6

eval instant at 5m histogram_quantile(0.5, incr_histogram)
	{} 1.5


eval instant at 50m incr_histogram
	{__name__="incr_histogram"} {{count:14 sum:24 buckets:[1 12 1]}}

eval instant at 50m histogram_count(incr_histogram)
	{} 14

eval instant at 50m histogram_sum(incr_histogram)
	{} 24

# We expect 12/14ths of the values to fall in the range 1 < x <= 2.
eval instant at 50m histogram_fraction(1, 2, incr_histogram)
	{} 0.8571428571428571

eval instant at 50m histogram_quantile(0.5, incr_histogram)
	{} 1.5

# Per-second average rate of increase should be 1/(5*60) for count and buckets, then 2/(5*60) for sum.
eval instant at 50m rate(incr_histogram[5m])
	{} {{count:0.0033333333333333335 sum:0.006666666666666667 offset:1 buckets:[0.0033333333333333335]}}

# Calculate the 50th percentile of observations over the last 10m.
eval instant at 50m histogram_quantile(0.5, rate(incr_histogram[10m]))
	{} 1.5



# Schema represents the histogram resolution, different schema have compatible bucket boundaries, e.g.:
#  0: 1 2 4 8 16 32 64 (higher resolution)
# -1: 1   4   16    64  (lower resolution)
#
# Histograms can be merged as long as the histogram to the right is same resolution or higher.
load 5m
	low_res_histogram	{{schema:-1 sum:4 count:1 buckets:[1] offset:1}}+{{schema:0 sum:4 count:4 buckets:[2 2] offset:1}}x1

eval instant at 5m low_res_histogram
	{__name__="low_res_histogram"} {{schema:-1 count:5 sum:8 offset:1 buckets:[5]}}

eval instant at 5m histogram_count(low_res_histogram)
	{} 5

eval instant at 5m histogram_sum(low_res_histogram)
	{} 8

# We expect all values to fall into the lower-resolution bucket with the range 1 < x <= 4.
eval instant at 5m histogram_fraction(1, 4, low_res_histogram)
	{} 1



# z_bucket:1 means there is one observation in the zero bucket and z_bucket_w:0.5 means the zero bucket has the range
# 0 < x <= 0.5. Sum and count are expected to represent all observations in the histogram, including those in the zero bucket.
load 5m
	single_zero_histogram {{schema:0 z_bucket:1 z_bucket_w:0.5 sum:0.25 count:1}}

eval instant at 5m histogram_count(single_zero_histogram)
	{} 1

eval instant at 5m histogram_sum(single_zero_histogram)
	{} 0.25

# When only the zero bucket is populated, or there are negative buckets, the distribution is assumed to be equally
# distributed around zero; i.e. that there are an equal number of positive and negative observations. Therefore the
# entire distribution must lie within the full range of the zero bucket, in this case: -0.5 < x <= +0.5.
eval instant at 5m histogram_fraction(-0.5, 0.5, single_zero_histogram)
	{} 1

# Half of the observations are estimated to be zero, as this is the midpoint between -0.5 and +0.5.
eval instant at 5m histogram_quantile(0.5, single_zero_histogram)
	{} 0



# Let's turn single_histogram upside-down.
load 5m
	negative_histogram {{schema:0 sum:-5 count:4 n_buckets:[1 2 1]}}

eval instant at 5m histogram_count(negative_histogram)
	{} 4

eval instant at 5m histogram_sum(negative_histogram)
	{} -5

# We expect half of the values to fall in the range -2 < x <= -1.
eval instant at 5m histogram_fraction(-2, -1, negative_histogram)
	{} 0.5

eval instant at 5m histogram_quantile(0.5, negative_histogram)
	{} -1.5



# Two histogram samples.
load 5m
	two_samples_histogram {{schema:0 sum:4 count:4 buckets:[1 2 1]}} {{schema:0 sum:-4 count:4 n_buckets:[1 2 1]}}

# We expect to see the newest sample.
eval instant at 10m histogram_count(two_samples_histogram)
	{} 4

eval instant at 10m histogram_sum(two_samples_histogram)
	{} -4

eval instant at 10m histogram_fraction(-2, -1, two_samples_histogram)
	{} 0.5

eval instant at 10m histogram_quantile(0.5, two_samples_histogram)
	{} -1.5



# Add two histograms with negated data.
load 5m
	balanced_histogram {{schema:0 sum:4 count:4 buckets:[1 2 1]}}+{{schema:0 sum:-4 count:4 n_buckets:[1 2 1]}}x1

eval instant at 5m histogram_count(balanced_histogram)
	{} 8

eval instant at 5m histogram_sum(balanced_histogram)
	{} 0

eval instant at 5m histogram_fraction(0, 4, balanced_histogram)
	{} 0.5

# If the quantile happens to be located in a span of empty buckets, the actually returned value is the lower bound of
# the first populated bucket after the span of empty buckets.
eval instant at 5m histogram_quantile(0.5, balanced_histogram)
	{} 0.5
