# 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